documentation comprehension woes for a n00b

Discussion forum for Extension Writers regarding Extension Development.
Post Reply
ekdikeo
Registered User
Posts: 30
Joined: Tue Oct 28, 2014 8:56 pm

documentation comprehension woes for a n00b

Post by ekdikeo »

That's me, the phpbb n00b. Before you all chime in with a chorus of "THIS DOCUMENTATION ISN'T MEANT FOR YOU, N00B", keep in mind that I'd like to rapidly become not a n00b, and hopefully improving on these things will help us all become not-n00bs.

Comments are welcome, but I'm trying to be constructive, so please try to be constructive with me. Thanks :-)

If you'll follow along with me here, on https://www.phpbb.com/extensions/writing/ , as I read through this documentation, I'll explain how I'm understanding/not understanding it here, and I'm hoping that people who do have the knowledge that I'm currently lacking can improve on it, so that I/we can all gain more knowledge today than we had yesterday.

"Writing Extensions" -- ok, I get this section. Looks good.

"How To Write An Extension" --
- Would highly recommend against using GPL license for the demonstration extension, as people are probably pretty highly likely to just grab this and use it as a template for further development. Those of us who are not going to be using GPL, however, pretty much have to not even look at it, lest we potentially be accused of including GPL code within something that has a different license.
- "The example detailed below"..., doesn't actually demonstrate how to write a basic extension that will add a new page to a board. There is nothing of the sort actually detailed below. There are some descriptions of some various concepts, which are probably likely used inside the demo, but very little code is detailed.
- The example of a composer.json is good, however, a link to full documentation on all parameters available, as well as what is required and what isn't required, would be very handy here.

"Extending the Base Class With ext.php" --
- This reads as "Here is a step we're going to describe that has absolutely nothing to do with the demonstration code that we asked you to look at."
- Followed by "this would not be required for most extensions", but for a layman, it kind of seems like it's actually something that most extensions would need -- wouldn't they need to perform some actions upon enable/disable/purge?
- Little description of what the ext.php functions actually do -- we can tell that they are called at enable, disable, and purge. Discussion of the serialised data return. No discussion of what you're actually expected to return from any of these functions, other than at some point, someone wants a "false" response. What does "false" mean? And why the talk of "...when enable_step() is called again"? What causes enable_step() to be called multiple times? "This could be effected by the script redirecting onto itself" .. is it caused by that? or is it caused by some other external thing?
- disable_step and purge_step can be used in a similar way -- similar implies that they are not the same, are they used in the same fashion?

"Controllers" --
- This reads "Controllers can be placed anywhere, can be called anything, and do not have a specific, defined interface to them", "we suggest you put them in a directory called controllers". "A function can be defined, that we call handle(), but you can call it anything you want, which will somehow handle requests to display pages."
- "You don't need to declare standard globals" (duh? why would you declare something that exists already?)
- Immediately after this, the documentation breaks down completely. It goes into the Services and Routing sections, without any sort of description whatsoever, of what we're talking about, a description of anything in the files, the variables that it mentions, these two sections are completely unreadable without significant prior knowledge.

"Including Files"--
- "Here's another section referring to something not at all used in the demo, but you really should use it yourself."
- Paragraph 2 and 3 feels like they are incredibly obvious, which likely means that they need a lot of clarification.
- re: IN_PHPBB. Wouldn't it be so much better to throw in a file in the phpbb include path, that must be required at the top of all files, that simply states

Code: Select all

if(!defined('IN_PHPBB')) exit;
[code]

"Modifying Existing Functionality" -- I thought that's what this entire document was about?
- Core events section: This section doesn't actually describe anything about events, other than that they are somehow located in an "events" directory.  Are they php code? data files? There's some talk of some code that is presumably over in that github repository, but without any explanation of it, other than it subscribes to an event (how?) it receives an event variable (but it looks like events do not have a specific interface, ie the variables given to them could be different?)
- Template events: ... i dont' understand this section. I just don't grasp it, other than that it's talking about including css and js.

"Language Files" -- this section looks ok, but doesn't tell you where/how to actually call the function it says you need to call.

"Template Files" -- looks like this section is ok, but could use a link to further documentation.

"Migrations" -- Seems to be missing a large amount about how to actually use something.  Documents functions you need. Doesn't document at all how to do anything with it, and little of "why".  My guess is that the "why" is the reason why I would think we would want to use the "ext.js" above.
technogeek12
Registered User
Posts: 49
Joined: Fri Jan 31, 2014 3:09 pm

Re: documentation comprehension woes for a n00b

Post by technogeek12 »

Documentation sure is lacking....... I'm sorry to say that I can't grasp what these docs are talking about.
I've been taking a peek at other MODs and trying to figure 'em out. Not much progress so far.

Edit : MOD -> Extensions
vipaka
Registered User
Posts: 492
Joined: Sun Aug 28, 2011 7:25 pm
Contact:

Re: documentation comprehension woes for a n00b

Post by vipaka »

" You don't need to declare standard globals" (duh? why would you declare something that exists already?)"

--you actually do, just in a different way (to my understanding). I've been poking around with the new 3.1 system for a few hours now, and if I'm right, you have to declare the global variables you wish to use in the services file (and then the __construct function of the controller file) in the same correct order. There is NO documentation anywhere I can find with a full list of the global variables and their new service handlers (like $db is now @dbal.conn and @dbal.tools and I have no idea what each of those does, and then in the construct function again, no documentation for what those should be called). And if you call it wrong, you get a fatal error on any new pages you've created saying the argument for construct is somehow wrong.

https://wiki.phpbb.com/Event_List That is a list of documented events, assuming the arguments are listed in the correct order for each one. Events are used in the controller files to access different areas of the board without the necessity of modifying the files directly (as was the case in 3.0). So whereas before you might have to replace lines in one of the core files to make a mod work, now you'd just use the event like core.modify_posting_parameters(post_id) (and any other arguments). I myself am not 100% on how to correctly use events, but hope that helps a little at least.

Please excuse any mistakes, I really don't understand this system very well at all yet, just trying to help out with what little I have figured out so far.

Functional example (ish)
services file arguments (what was in 3.0 the line global $config, $db, $template, $user;)

Code: Select all

            - @config
            - @dbal.conn
            - @controller.helper
            - @template
            - @user
construct function in controller file (again, before all of this was handled with one line calling global variables, now it is passed from services to the construct function)

Code: Select all

protected $config;

	/* @var \phpbb\controller\helper */
	protected $helper;

	/* @var \phpbb\template\template */
	protected $template;

	/* @var \phpbb\user */
	protected $user;

	protected $db;
	/**
	* Constructor
	*
	* @param \phpbb\config\config		$config
	* @param \phpbb\controller\helper	$helper
	* @param \phpbb\template\template	$template
	* @param \phpbb\user				$user
	*/
	public function __construct(\phpbb\config\config $config, \phpbb\db\driver\driver_interface $db, \phpbb\controller\helper $helper, \phpbb\template\template $template, \phpbb\user $user)
	{
		$this->config = $config;
		$this->helper = $helper;
		$this->template = $template;
		$this->user = $user;
		$this->db = $db;
	}
Calling the following function from within the handler function results in a print out of all usernames for every registered user, I'm guessing this is how queries should be handled from within controller files.

Code: Select all

public function handle($name)
	{
		$l_message = !$this->config['acme_demo_goodbye'] ? 'DEMO_HELLO' : 'DEMO_GOODBYE';
		//this is just php for the acp based config condition of the hello world demo extension.
		$this->template->assign_var('DEMO_MESSAGE', $this->user->lang($l_message, $name));
		//this tells it what message to print, although I don't know if the , is the replacement for the 3.0 => or if that's just because a language variable is used here.

		$sql = 'SELECT username
						FROM ' . USERS_TABLE . '
						WHERE user_id > 0';
				$result = $this->db->sql_query($sql);
				while ($row = $this->db->sql_fetchrow($result)){
				      print_r($row);
				}
				return $this->helper->render('demo.html', $name); 
				//this tells the controller what the name of the template file is (demo.html), and the title to display on the header of the page (the value of the $name varialbe).
	}
"Mods" in 3.0 are now "Extensions" in 3.1. The php file for a mod (in most cases) was located in the root directory of the phpbb folder, now it is divided into multiple files and all stored in the ext folder. The controller is essentially the main file, somehow relying on the services and route files as well for global variables and different routing rules. The template html files goes in the same place as before (styles->your style -> template) and seems to have only minor changes to the syntax of 3.0 statements. Same goes for language files.

old: root/my_mod.php
new: root/ext/my_username/controllers/my_mod.php
and root/ext/my_username/services/services.yml
old: root/styles/prosilver/template/my_mod.html
new: root/ext/my_username/styles/prosilver/template/my_mod.html
old: root/language/en/mod/my_mod.php
new: root/ext/my_username/language/en/mod/my_mod.php

The biggest problem I'm finding is that although there is *some* documentation for the new syntax expected in controller files, I can't find much of anything about the construct function or using events properly. Once that's documented and the other stuff...3.1 extensions should start cropping up a lot faster.
Curious about my work? See it for yourself.
Image
ekdikeo
Registered User
Posts: 30
Joined: Tue Oct 28, 2014 8:56 pm

Re: documentation comprehension woes for a n00b

Post by ekdikeo »

There's little useful discussion of the services file -- where they are located, what they are called, how they are used, what they contain, what they do.

I "get" most of what you say when you compare it to before, but I was only here 1 day before, so I figured I'd just wait to develop something until this came out :-) It would be helpful if it were explained in a way that doesn't rely on comparing it to what was before (although the comparison I'm sure would be helpful for people who did it the old way, even those comparisons in the document are possibly too general)

The template section really just needs a link to documentation for the new and old system, and hopefully one of those links would have some discussion about why you would use one over the other.
Khaos-Rage
Registered User
Posts: 71
Joined: Sun Jul 13, 2008 4:31 am

Re: documentation comprehension woes for a n00b

Post by Khaos-Rage »

Most of the components of phpBB 3.1 are using Symfony 2 components so some of what you (and what I have been looking over) for is documented at their site. The easiest examples of which are the controller and routing information. http://symfony.com/doc/current/book/index.html

Other information I have looked at for reference is the yaml config files in the config directory.

Just as an example since you mentioned the dbal.conn. I believe most of the information can be pulled from these files or mainly the services.yml file. This is from the db.yml file in the config directory.

Code: Select all

services:
dbal.conn:
class: phpbb\db\driver\factory
arguments:
- @service_container
dbal.conn.driver:
class: %dbal.driver.class%
calls:
- [sql_connect, [%dbal.dbhost%, %dbal.dbuser%, %dbal.dbpasswd%, %dbal.dbname%, %dbal.dbport%, false, %dbal.new_link%]]
dbal.tools:
class: phpbb\db\tools
arguments:
- @dbal.conn
If I'm wrong or am a little off then someone correct me ;)
ekdikeo
Registered User
Posts: 30
Joined: Tue Oct 28, 2014 8:56 pm

Re: documentation comprehension woes for a n00b

Post by ekdikeo »

That seems like a very handy link that, I guess I'll be reading some of that on my next plane trip today.

It seems like it'd be really awesome if someone could actually come up with a good explanation/documentation of these yml and services or something. Or maybe there is one, and it just should be linked from the extension tutorial.
User avatar
MattF
Extensions Development Coordinator
Extensions Development Coordinator
Posts: 5351
Joined: Sat Jan 17, 2009 9:37 am
Location: Los Angeles, CA
Name: Matt Friedman
Contact:

Re: documentation comprehension woes for a n00b

Post by MattF »

The writing extensions article you point to is meant to walk through the files that make up the acme-demo, which basically covers all the main points of extension's development.

That article is for developers, and as such, expects the reader already has a firm grasp of php, javascript, css and html. Of course composer and symfony frameworks are new to phpBB 3.1, but they are too dense for us to cover in an article about extensions. We assume that you, as developers, either already know those frameworks or can use simple google searches to read up on their documentation and learn from them if you feel you require a deeper level of understanding of them.

It probably would be a good idea to add links to those frameworks documentation at the bottom of the article in the additional resources section though.
Formerly known as VSEMy ExtensionsPlease do not PM me for support.
User avatar
Walther
Registered User
Posts: 284
Joined: Fri Jul 09, 2004 5:21 pm
Location: The Netherlands

Re: documentation comprehension woes for a n00b

Post by Walther »

VSE wrote:...
That article is for developers, and as such, expects the reader already has a firm grasp of php, javascript, css and html.
..
oh, that makes me feel better, because I got al enthusiast when I did read the 2 first sentences where the article started with
If you are an existing developer or a phpBB board owner thinking about learning PHP there has been no better time to get involved in the extensions community.
..
ending up feeling really dumb about not knowing what all the controller yiby-yaby-talk was for example :cry:

I always had the idea that a "hello world" example is a step-by-step instruction to your first program/script/project.
So i started with making the directory acme in the ext dir, making a subdir called demo, and then there was not much more then a composer.json
Sure, one can download the whole extension pre-typed, call me oldscool, I'm learning better by typing it and fidling with it. :idea:
Post Reply

Return to “Extension Writers Discussion”