Documentation and Implementation Improve

First let me say that i am a Brazilian PHP developer (Manuel, sorry but I'm speaking in English so all others can understand), and my English is not so good, than apologize for any mistakes.

I started to look around and learn how to use this class, and I can see is that is a wonderful class that have lots of good things already done, keeping us to implement all the stuff again.

My idea here is to propose and special look into this class so we (developers and users) can use and learn it much more easily.

I am talking about some documentation improvement, API Documentation creation, implementation improvement creating a branch for PHP 5- and another one to PHP 5+ with all the OOP that PHP5 provides: like changing the deprecated 'var ' declaration variables in the classes, the lack of methods and one single function doing lots of tasks. Although that, implementing the best plugins as native in the class, and using the patterns that is most acceptable in the new PHP IDEs, like comments in functions and indentation features (If I'm not wrong we can find these things with a bit of Googling).

These ideas and any others that may appear could be done too.

In a first glance i can imagine a SVN with a Trac feature that would keep all users in touch about what is being modified and implemented in each version of that.

If you do like the idea let's stay in touch so we can improve this class over and over.

Thanks in advance,

Everton Moreth

Thank you for your interest.

I am not sure everything you suggest is viable. Let me explain

- API documentation creation: the class API is already fully documented .

- PHP 4/5 versions: I am not sure this is a good idea. It would take much more work to maintain and I don't see that providing more value to most users.

- var deprecated: I think that was a bad idea of the core PHP developers. Changing var to public does not change nor add anything. Only makes you PHP issue a warning in strict mode, but there is nothing wrong with that. var was just renamed to public. If I am not mistaken there was a plan to make PHP 5 not complain about var anymore, as it is really not a problem.

- Lack of methods? Which methods?

- Single functions doing lots of tasks? Which functions? Is that a problem? Isn't it simpler to call a single function that does several things depending on the context, rather than having to write more code to do the same, like in Java?

- Implementing the best plug-ins as native in the class: plug-ins were implemented as separate classes to avoid bloating the main class further. A large main class makes PHP take more memory to execute. Actually, it would probably been better to offload some functionality that is not always used to plug-ins, like for instance credit card validation.

- Comments in functions: usually I prefer writing self-explaining code, than using comments. Adding more comments to the main class at this point would probably make it even larger. Some users are scared by very large classes. I would rather not make that problem worse with more comments in the code if I can live without them.

- SVN: the class code is also available in a public CVS repository

Feel free to comment or submit more ideas.

The API is created but it is not so easy do find things nor understand that... My idea is to make more interface on that.. just like the Google's APIs pages...

Lots of things had changed from PHP4 to PHP5, and many things that can be improved on PHP5 can't be done because of the compatibility of the code. The idea of the OO programming is to simplify your work making you need to change less code to do change something.

Changing the mean-less word 'var' to 'public' tells the programmer (or even the newbie programmer) the idea of that variable, once that know we can specify 'private' or 'protected' variables to protect our code and information from external user-mess. With that is obvious that this 'public' variable is accessible from class instance while private and protected can't.

The lack of methods that I'm saying is that you can't retrieve a unique information, because the method that generates that also generates a lot of other stuff. Or even to separate the code to make easier to find where are the stuff that you want to change and the need to analyze less code to understand what that method is doing.

The idea of OOP is to reuse all the code without the need to write it again and make a flexible code that can be easily changed to do whatever it needs. So if one function does a lot of things you just can't get separated parts of the code to do something slightly different. Although lots (most) of users are use to the OOP implementation (Javascript for example is fully OO, or even people who comes from Java, or C++) with encapsulation and heritage, these kind of programmer nowadays get totally lost with this class because it is fully created and configured with one single object, without code encapsulation.

Implementing the best plugins as native doesn't means that you will need much more memory. You can implement that without loading this and creating a option so the user can configure what parts of the class the class will load and provide functionality. The same way we can offload things like the credit card validation and make this as a plugin that may be loaded or not by the user.

The comments are usefull because of some IDE's that use it to provide information about the code. Just like the javadoc that looks the comments above each function to tell what each parameter expects, what that function returns and a short description about what that function does, that way you don't even need to look into the self explaining code (and that's the idea of any library: use... not change). PHP as you know does not need to specify the type of the parameters given (like Java for example) and so the informations provided by the IDE must come from the comments. Comments of all kinds does not increase processing in a significantly way. And even if makes, there are some programs that indeed to compress the code and easily remove them (This could be even another branch of that, a release version not for debug). The class is really large because it has lots of examples that in my opinion should be on the API page and not in separated files.

Another good point of the OOP changing is that the new IDEs can show you the methods and variables of each object, so with that, you can for example create a eventObject, that would contain only the event methods and functions like ONERROR, ONABORT, ONLOAD, ONUNLOAD ... Once that this eventObject is created and configured it would be associated with an input giving the input its values. The good point of this is that the IDE only shows events for you to choose instead of a huge list of methods and variables.

I am not sure if I understand you, but I need to be pragmatic here. Let me explain.

- The classes are large but there is plenty of things to be done. Therefore I need to sort the priorities to develop things that are really necessary.

- Personally I think that the differences between PHP 4 and PHP 5 do not justify the duplication of work that it would take to maintain two versions.

- If it is a matter to make it clear which functions are private or public, this package uses a convention, if it is documented it is public, otherwise it is private do not access.

You should always be looking at the documentation to learn how to use the class, rather than looking at the code. The documentation exists for that purpose.

- I understand that some functions provide many features within single functions. For now the class provides all I need. I will not go through the trouble of splitting large functions unless there is a specific need. If you need something that the class API does not provide directly, tell me and I will see what can be done to provide what you need.

- The fact that main class uses only one final object is intentional. Some forms may be complex and have many fields. For such large forms, it would be much slower and use more memory if I created many objects, one per input field.

If you have seen complaints by people that claim that other form packages that use many objects are slow, that is the reason.

- I am still not sure what you mean by implementing the best plug-ins as native. Currently the plug-ins work by specifying an input of type custom. The class that implements the plug-in is only instantiated when the input is added to the form.

This way each script only has to load only the classes that it needs. It may even use auto-load feature under PHP 5 to load classes automatically when the plug-in is needed.

If this not what you mean, you need to give me an example so I can understand what you are suggesting.

- Despite I do not use such IDEs that pick documentation from comments, I understand that can be helpful to people that use IDE that support. I will try to make some time in the future to add such comments.

Ok, let's dispose that PHP4/PHP5 idea...

That fact that what is documented is public is quite good once that you does not use a good IDE, because it considers the whole class as public and so shows to you a kilometric list of things that you could use, but at really you should just use some of them. But i agree that if it have to be PHP4 compat there is no way to solve that (maybe just improve a little).
Still talking about the IDE, passing things on variables instead of associative arrays brings to you the auto-complete feature which provides you for example the list of all events (the almost always are ON******) just typing $form->ON, it makes the programmer life much easier.

That idea of splitting large functions are to make easier to create custom inputs, once that you could retrieve once single information, for example if i had to create a custom email verification that verificates if the email is valid and if it is my own domain, i could get your code to verify email and add my personal check after it (obviously this code is quite simple, but may be others that aren't). Or even if i want to change a little thing on your files to fit my needs i could just override a function and extend one class with that.

I cannot see a real machine that have enough processing capacity to go through many PHP requests and have a so small memory that would overload the system capacities with the object creation. I made some tests with a little class and an array saving the same values, storing the values as associative arrays and as properties of the class, creating them with a for statement and keeping them on another array. What i found is that until i get on values lower then 1000 objects the increase of memory between array and object is lower than 5% and at 100000 objects the increase is on 10% (i really can't see a server that can process 100000 PHP requests at same time and does not have enough memory to afford it). I think we have to consider that forms are not always seen everywhere, and that PHP frees the memory once the script finished. Anyway, using destructors as they should be used is a good thing too.

I could help with some other things that may be helpful like the variable $validate_as_set that is declared on line 2470 of forms.php and never used again in any part of the code (plugins, custom, examples, docs, anything...), or even adding the ';' on the JavaScript (wich are part of the good-manner JavaScript Programming) allowing the users to create the JavaScript without line-breaks with no headache (what is very useful to avoid hack tries).

I'm obviously don't want to make you unhappy, but two heads think better than one... Okay.. in your case n+1 heads think better than n. But anyway four hands type faster than two. I don't want to take your credits on this nor contest your programming skills (i know that you are one of the best PHP Developer nowadays ). I just want to help a project that i really saw as a great project and learn a little if i can. I don't intend to do anything that you don't allow or even disapprove. I'm just offering help to solve/help solving the low priority things in the class.

PS.: I don't know if you have a way to see how often this topic is being seen, but if there is only us looking into it we can write in portuguese.

One more time thanks for your patience and time.

1. I tried Kate, Quanta and PDT and none seems to provide support to add PHPDoc comments. I do not have time to add that manually.

If you are interested in adding such comments, just add it to the latest class version and send it to me so I can integrate the changes. Just make sure you do not change the formatting of the rest of the class code, so I do not waste time figuring what was changed.

2. As I mentioned, I do not have time to split the code of all possible functions people want to use directly or override. I may do it on demand if there is a real world need that may require a functionality integrated inside existing functions.

Just let me know if you need something specific that could be extracted from an existing function to a separate function.

3. The memory problem when using many objects becomes evident when you use large base classes with many variables or functions. That would be the case when you use a base class to provide base services for different types of inputs.

I could have used the base plug-in class to create separate classes for all base types of inputs. I did not do it for the reason above.

4. I have fixed that case of unused variable in my current version. If you find more cases of unused variables just let me know.

The generated Javascript for use in HTML attributes usually already ends with semi-colon precisely to allow eventual concatenation of custom Javascript. When you end statements breaking lines there is no need for semi-colons.


Other than that, your criticism is always welcome, even if it seems there is a misunderstanding on your part of why certain things are the way they are.


This package forum is subscribed by several people that follow all threads. So lets keep writing in English.

Hi,

I silently followed the discussion, and wanted to add my 2 cents.

I use Zend Neon (extended PDT) and ZendFramework 1.5 together with formgen. (never found the time to get into Zend_Form and to be honest didnt really like it).

I dont understand that I was able to use KATE for coding a few years back. (Used ZendStudio befor Neon) an IDE changes your coding and the speed you produce the code.

For the PHPDoc Comments, in Zend Neon you can position your cursor a line befor eg. a class, type /** hit enter and it writes the phpdoc for the defined vars and return value automaticly. see http://www.iamjacks.net/phpdoc.png for an example. I guess PDT handles it the same way.

As much as i would love to see a PHP5 version of formgen. I also see no point in it at the moment. I have my on form class which extends the formsgenclass. The forms i define are in own classes which extends my form class (and using an interface just for fun) This works pretty well for me.

See the shortend examples:
iamjacks.net/form_example.phps
iamjacks.net/exampleController.phps
iamjacks.net/result.png (a little complexer form, not from the example)

If someone is in need i can publish bestHeads_Form and bestheads_Form_Interface (with absolutly no warrenty :-)

my2c
Ludwig

Zend Studio for Eclipse (Neon) and PDT are the same product but Zend excluded some modules like PHPDoc comment creation support.

I tried Zend Studio for Eclipse and can see that it simplifies the like of those that want to add PHPDoc comments.

Anyway, right now I do not have time to add PHPDoc comments. If anybody with some time and patience would be willing to do that for the main forms class, I would gladly review and integrate those comments so starting next release anybody could benefit from the PHPDoc metadata in IDEs that support it.