Forms (Symfony\Component\Form)

Forms are created through a Factory service (form.factory), which subsequently uses a Builder object, to automate the creation of fields and assembly of the Form Composite tree. The best way to illustrate and explain this process is to walk through an example usage scenario.

$myForm = $this->createForm(new MyType(), $entity, array(...));

Symfony’s Controller class (Symfony\Bundle\FrameworkBundle\Controller\Controller) defines the createForm method shortcut, which accepts the following parameters: a string identifier or an instance of a Type class, an entity to which the form will bind its information, and an array of options to pass to the Type’s buildForm() function. The last two parameters, the entity and the options array, are optional. If no entity is provided, then the data can be retrieved by calling $form->getData() after binding.

Controller::createForm() delegates to FormFactory::create(). FormFactory acts as a Façade to the Form component by automating and abstracting much of the creation process. FormFactory::create() then delegates to a FormBuilder object, which creates the form recursively for each of the nested Type objects. Afterwards, the FormFactory returns the completed Form tree by calling $builder->getForm().

class MyType extends AbstractType {...}

This is the definition of a Type class that will control how a node on the Form tree will be constructed by the builder. Note that Symfony 2 discourages users from directly defining Form subclasses: using the builder reduces dependency on the Form’s interface and allows its internal structure to vary as Symfony evolves without affecting the user’s code.

public function buildForm(FormBuilder $bldr, array $opts) {...}

This function is a member of the MyType class and is the callback for when a node of type MyType is created. The form factory passes a builder to this callback so this node’s children can be created (even recursively, if necessary by calling $fieldOrSubForm->buildForm($bldr, array(...))). The options are passed from the parent node (or the constructor if this particular Type object was instantiated) and can be used to dynamically configure form elements.

$bldr->add('name', 'text', array('required' => true));

This statement would reside in the definition of MyType::buildForm() and gives me the opportunity to explain how the builder works. The builder’s add function creates a child on the current Form node with the given arguments: name, type, options.

• The name acts as an identifier for the child (and the input field’s name attribute when rendered as HTML), much like the key to a PHP array value.
• The type is optional and can be either a string or an instance of Form (or any of its subclasses, including Type objects). If omitted, the builder can guess the type using doctrine metadata. If a string is given for the type, the builder uses it to look up the type class in a registry of built-in Type classes (all of which are defined in Extension\CoreType). I cannot determine whether the registry of built-in types follows the Flyweight pattern or the Prototype pattern (or a combination of both), but that’s not important now. If a Type instance is given, the builder can skip the lookup step and process it immediately. This is how one can embed a form within a form in Symfony 2.
• The options array will be used for configuration in the child node’s buildForm() method. Note that the ‘required’ option in the code example above is NOT a part of the validation model. Rather, it is an HTML5 attribute that is added to the rendered field for browser-based, client-side validation. This is not meant to be used in place of server-side validation as the ‘required’ attribute is not supported by all browsers.

When the builder creates a child node, it sets the new node’s parent reference to the current node that called for the child’s construction. The builder is actually a lot more complicated than how I have explained it here: it uses lazy loading so that it does not create any child objects until it absolutely has to. Calling $builder->getForm() triggers this mechanism. The resulting Form object will allow for data binding and validation and acts as a wrapper for the data object underneath.

return array('view' => $form->createView());

Because the Form object only serves as a wrapper to an entity, array, or other data form, it cannot be rendered into HTML as-is. To resolve this, the controller passes an instance of FormView to the templating engine at render-time. A FormView is a PHP abstraction of the HTML input tags and provides a way for the templating engine to iterate over the fields in the form.

In summary, the FormFactory is the main interface for the Form component; the FormBuilder is responsible for adding fields (Types) to the Form object being built; the Form is a lightweight composite wrapper for the data object that stores the information, and the FormView encapsulates information pertinent to rendering HTML input fields.

Entities

Dynamic web applications depend heavily on storing and retrieving data. Symfony has altered the traditional norm in favor of Domain Driven Design.

Entities are nothing more than plain-old PHP classes that mimic the properties and behavior of real-life objects. They do not extend any base Entity class and are thus entirely self-contained. This is another reason Symfony is so fast and lightweight. Entities help the Symfony framework feel more like working with a statically typed object-oriented language like Java or C++.

Entities are persisted by the Doctrine ORM. The ORM understands how to communicate with the entities because of the metadata information associated with the fields to be saved and by conventional getter and setter names. I prefer using annotations because I can define mapping and validation metadata for each field in the same file. I am also amused by the fact that Doctrine (and other Symfony components) can read and cache the PHPdoc comments that are ignored by the PHP interpreter. Symfony also provides ways to configure entity metadata using YAML, XML, or PHP files.

Validation (Symfony\Component\Validator)

Validation, the act of checking data legitimacy, has traditionally been closely integrated with forms: when a user submits data, a validation script checks that all required fields have been filled, certain numeric or date values are within a predetermined range, and email addresses are correctly formatted. Validation also applies on a coding level: a RESTful web service could submit information directly into the controller without the use of an HTML form; unit tests populate entities directly through setter methods.

Validation must be made available to both Forms and Entities. Symfony 2 solves this problem by extracting the validation subsystem into its own Validator component. According to the Symfony 2 online documentation, “This component is based on the JSR303 Bean Validation specification.”

Like Doctrine, the Validator component knows how to validate an object based on metadata, which can be defined on the Entity using Annotations or in separate YAML, XML, or PHP configuration files. Regardless of how the metadata is defined, the Validator caches it for faster performance.

There are two ways to use the Validator component: either directly or through the Form component. Using it directly is very straightforward. From the controller level, the Validator service can be obtained by calling $this->get('validator'). Inside a Unit test, the Validator is created with ValidatorFactory::buildDefault()->getValidator(). Once we have a Validator, we can pass it an entity to be validated:

$validator = $this->get('validator');
$errors = $validator->validate($entity);

When binding data to a Form, the Form object automatically transfers the data to the underlying entity object and calls the Validation component to check it.

I’ve previously written about the Symfony 2 PHP framework, and as the release date draws near (currently in RC6—it has to be soon), I’ve been trying to help the Symfony developers solve user-reported issues on their public repository. Many issues are categorized under “Forms”, so I’ve been trying to understand how Symfony’s Form component works. I had attempted to do this prior to reading Design Patterns and was very confused by all of the abstraction and delegation to other classes. Now that I understand more about software design, it’s much easier to fit the pieces together:

In Symfony 2, the Form component is a Factory Façade object that provides access to a Composite object (enabling embedded forms) that is created via a Builder that delegates type-specific configuration to Flyweight Type objects… These are just a few of the simple design patterns that I’ve read about!

There are many other design patterns used throughout the Symfony framework: a huge indication that it is well-designed. This is most likely the reason behind its incredible speed and low memory footprint.

In general, Symfony 2 is much lighter and faster than all of the other PHP frameworks I’ve used (including CakePHP, Zend, and CodeIgnitor). At the time of writing, the current version is 2.0.0 Beta 3, and as I have learned more about this revolutionary redesign, I have come to understand more about the inner workings of the Internet rather than relying on “automagic” components. Symfony 2 offers a way of dealing with HTTP requests and responses in a familiar, object-oriented, MVC fashion. I won’t bother to explain the exact details, but I will summarize:

An HTTP Request begins its journey when the user performs an action on a web page. For simplicity, suppose the user clicks a link to an “About” page and makes a simple GET request. In a Symfony 2 application, the request is caught by the front controller, a single file that handles all requests and passed to a Kernel for processing.

The Kernel analyzes the request and matches it to a route defined in a cached configuration file. If the route matches a firewall pattern protecting a certain resource, then the user may be asked to provide authentication credentials (i.e. redirected to a login page). The route redirects the response and its parameters to a controller action that resides in a “Bundle”

The Controller handles the request and performs any logic to gather information from a database (if necessary). At this point, the “Model” paradigm has been replaced by Entities—plain-old standalone PHP objects that can be saved (or persisted) to a database by an external entity management service (in Symfony’s case, Doctrine). Symfony 2 also provides support for the Document storage design popularized by the MongoDB database engine.

After performing all necessary logic and processing, the action returns a response object, which could be anything from a redirection to a JSON file to an HTML page. This response is handed back to the client’s web browser.

Traditionally, HTML responses are rendered in templates. Symfony 2 uses a new templating engine called Twig, which uses syntax highly similar to the Python Django framework. The Twig is rendered as PHP and then cached for easy reuse.

Without any additional logic, a simple GET request in Symfony 2 takes less than 50 milliseconds to process, render, and return a response. A complex POST request that persists information to a database and fetches more information takes slightly longer: usually less than 100 milliseconds.

The Symfony 2 documentation offers more information, and I highly recommend reading the first couple parts it even if you aren’t a web developer. If, on the other hand, you are a web developer, Symfony is insanely fast, easy to learn, and powerful/flexible enough to customize your own core components.

Since both of these courses require special formatting and special characters, I’ve been delving more into the LaTeX ^[1] markup language for taking notes. Writing raw LaTeX in a plain text editor has proven to be more straightforward and more powerful than using a WYSIWYG word processor (like Microsoft Word or LibreOffice ^[2] Writer). Granted, LaTeX has a steep learning curve, but the compiled output looks extremely uniform and professional: LaTeX is to printed documents as HTML and CSS are to web pages.

Because LaTeX markup is plain text, it can be shared and tracked using a versioning system like Subversion or Git. The only other word processing system (that I’m aware of) that offers this kind of collaborative editing is Google Docs. Microsoft Word, Rich Text, and Open Document file formats are all stored in either a binary package or cryptic markup—both of which are hard to track with versioning/collaborative software. LaTeX, on the other hand, has human-readable source code.

By default, the latex executable outputs to DVI files, but LaTeX packages like TeX Live include pdflatex, which outputs to more universally-accepted PDF files. For more information about obtaining a distribution/build for your system, visit the LaTeX home page.

I understand that LaTeX is not for everyone. Some people do not need the fine-tuned control that LaTeX offers—in which case Microsoft Office, LibreOffice, or another word processor would better suit that person’s needs. Some might not have the time required to learn LaTeX. Nonetheless, I recommend it to anyone looking for a powerful markup-based word processing tool for writing books, articles, reports, or even letters.

Until next time, Gig ‘em and God bless!

Footnotes

1. ↑ I had mentioned LaTeX before when setting up math rendering in MediaWiki, but the packages that power this feature in MediaWiki aren’t even a snowflake on the tip of the iceberg! For a good example of what LaTeX can do, look at any textbook: symbols, math-type, columns, listings, images, figures, graphs, charts, plots, diagrams, tables, indices, appendices, bibliographies, cross-references, chapters, sections, typesettings, formatting, whatever—LaTeX can do all of it (and still even more).
2. ↑ When Oracle acquired Sun Microsystems and all of their products (including OpenOffice.org), the founders of the OpenOffice.org project decided to form an independent organization—The Document Foundation. However, Oracle has not allowed them to continue using the name “OpenOffice.org”. After improvements and rebranding, The Document Foundation released LibreOffice 3.3.

I have been a Linux fan for several years, and I still use it on a regular basis: all of my family’s Windows computers can dual-boot into Linux (Ubuntu for easy computing, ArchLinux for powerful custom installations). Additionally, I have a dedicated server at my house running Ubuntu Server 10.10 (terminal-only; no GUI) that serves as:

• a print server,
• a file server for my local network,
• an IRC server,
• a web server for many sites including my notes,
• a Subversion server for all of my coding projects, and
• a SSH server for remote administration.

The server automatically updates and remotely backs itself up, so maintenance is almost non-existant. I find it impressive—if not mind-boggling—that the “powerful” computer that performs these feats is an obscenely old 3.2 GHz single-core Compaq Presario with less than 1 GB of RAM that was built before HP even considered acquiring Compaq.

I recall a time before the Linux server in which printing to a shared printer was difficult & slow—if it even worked—and could only be done from Windows. It would seem that Linux solved all of my networking problems and provided a whole bunch of goodies in the process… I wonder why I didn’t set up this server earlier.

What about you? Do you use Linux? If so, what is (are) your favorite distro(s)?

The full path to executables can be ascertained with the which command (e.g. which apachectl)

Apache 2.2

Executables: apachectl, httpd
Configuration: /private/etc/apache2/httpd.conf

PHP 5.3.3

Executable: php
Configuration: /private/etc/php.ini

PHP is disabled by default, but relatively easy to enable.

MySQL 5 (Mac OS X Server Edition Only)

Executable: mysql, mysqladmin
Configuration: /private/etc/my.cnf

MySQL 5 comes bundled with Mac OS X Server, but the Apple Developer website explains how to install MySQL on Mac OS X for the rest of us.

I also find that I write long blog posts every once in a long while. In order to boost my blogging habits, I will try to post short, meaningful posts at a greater frequency, so I’ve also been looking for a theme that makes the most out of a little content. Full-width themes with small fonts make my blog feel empty, and adding links to the sidebar and footer to take up space make the site feel like “information overload”.

I believe I have finally found what I have been looking for: The Erudite by Soma Design fits my taste perfectly. I can’t wait to start writing!

Apache, MySQL, PHP, ImageMagick, LaTeX, Inkscape, MediaWiki, OCaml, Make, and G++

Note that I’m running these packages on Mac OS X. Also note that they are GNU Linux packages. (If you aren’t laughing yet, consult the infinite acronyms and trivia below)

GNU stands for “GNU’s Not UNIX” ‘s Not UNIX ‘s Not UNIX …
Linux stands for “Linux Is Not UNIX” Is Not UNIX Is Not UNIX …

Mac OS X is built on a Berkley UNIX BSD Subsystem, which means that it is a UNIX operating system; so the doubly-declared “Not UNIX” packages listed above are running happily on a UNIX machine… Just another reason why my MacBook is the ultimate hypocrisy.

Here’s how I did it (and so can you):

You’ll need the following packages. Download them now if you want.

• XAMPP server bundle (get the beta; it has PHP 5.3.2)
• MediaWiki CMS Framework
• Xcode Apple Developer Tools (free download after free registration; includes make and g++)
• MacPorts package manager (similar to aptitude/zypper/YaST/pacman on Linux)
• Inkscape SVG Plugin (optional)

Install XAMPP Server

1. Extract to /Applications (or wherever you want to install it.
   From now on, I’ll refer to this directory as $XAMPP
2. Run the following command in Terminal:
   

   $XAMPP/xamppfiles/xampp security

3. Launch Apache and MySQL from the control panel and/or load their daemons available in $XAMPP/xamppfiles/bin/ at startup
4. I configured XAMPP to use a virtual host to run MediaWiki, but it’s not necessary
5. (Optional) Add the following to /etc/hosts to make http://notes.local point to MediaWiki:
   

   127.0.0.1 notes.local

6. By default, Apache runs as ‘nobody’. Edit $XAMPP/etc/httpd.conf to run Apache as your user (short name).
   THIS IS A MAJOR SECURITY RISK IF YOUR SERVER IS PUBLIC, but it allows Apache to run files without much configuration.
   Alternatively, follow these instructions

Install MediaWiki

1. Extract to $XAMPP/htdocs (or the virtual host document root). I’ll refer to the MediaWiki root directory (e.g. /Applications/XAMPP/htdocs/w) as $MediaWiki from now on.
2. (Optional) Set up pretty URLs
3. Create the MySQL database on http://localhost/phpmyadmin
4. Visit Run the MediaWiki Installation to generate a LocalSettings.php configuration file
5. Move this file to $MediaWiki as instructed by the MediaWiki install wizard
6. (Recommended) Check out the other configuration options in LocalSettings.php
7. Install any desired extensions (I recommend Cite for Wikipedia-style footnotes).

If you want a simple installation of MediaWiki, you can stop here.
If you want Math, SVG, and other goodies, please continue.

Install Xcode Developer Tools

1. Run the install package

Install MacPorts Package Manager, etc.

1. Install MacPorts
2. Run the following command in Terminal:
   

   sudo port install ImageMagick teTeX texlive texlive-latex-extras ghostscript ocaml

This will take a long time and install a lot of packages, but don’t worry; they’re confined to /opt/local (/opt doesn’t exist by default on Mac OS X)
Update: teTeX is no longer a supported port; use texlive and its extras instead.

3. Run the following command in Terminal:
   

   sudo nano /etc/paths

4. Add the following to the end of the file and type Ctrl+X Y to save and quit (The guide to installing MediaWiki on Mac OS X makes this more difficult than it actually is):
   

   /opt/local/bin
/opt/local/sbin

Compile texvc (included with MediaWiki) and Activate Math

1. Recall from #6 on XAMPP Apache Configuration: If Apache is still running as ‘nobody’, check that you’ve modified render.ml appropriately
2. Open a terminal and run the following commands to compile the plugin between MediaWiki and LaTeX:
   

   cd $MediaWiki/math
make

3. Enable LaTeX and uploads in $MediaWiki/LocalSettings.php if you haven’t done so already.
4. Make archive/, math/, thumb/, and tmp/ directories inside $MediaWiki/images.
5. Make the images folder writable by executing the following command in Terminal:
   

   sudo chmod -R 777 $MediaWiki/images

Install Inkscape SVG Rendering Plugin

1. Install Inkscape to /Applications
2. Add the following lines to $MediaWiki/LocalSettings.php:
   

   $wgSVGConverter = "inkscape"
$wgSVGConverterPath = "/Applications/Inkscape.app/Contents/Resources/bin"

That concludes the advanced MediaWiki installation. Tweak $MediaWiki/LocalSettings.php to your liking: I’d love to hear what you come up with.

1. Consolidate all of your large photos, movies, and music onto a separate drive, if possible.
2. Find and delete any duplicated, outdated, or unused documents from your personal or shared folders.

Manually Archive/Compress Old Files

I highly recommend using 7-Zip. Use the 7-Zip format (.7z) with the “Ultra” compression setting: it will take longer, but it will save more disk space.

CCleaner

1. Download the latest version of CCleaner
2. Close all programs, especially web browsers
3. Check all options on both tabs except for wipe free space
   When you run CCleaner again, do not check old prefetch data
4. Analyze and Run Cleaner.
5. Click on the Registry tab
6. Scan for Issues and Fix all issues
   CCleaner will ask if you want to back up changes to the Registry. I have not had any problems with the registry cleaner, but it’s always a good idea to keep a backup.

Disk Cleanup

To open, right click on a Hard Drive in My Computer and click Properties. The Disk Cleanup option will be on the General tab next to the Disk Usage pie chart.

Be careful when using Windows Disk Cleanup that you don’t delete important files like the Hibernation file or the Office Setup Files

Remove Malware and Spyware

There are many free programs available around the internet to help with this task, but I highly recommend Spybot — Search & Destroy

Run a full scan and clean any issues that the program finds. (This may take a while depending on your computer).

Defragment your Hard Drive

Use either the built-in Windows defragmenter (Right-click on a drive in My Computer, go to Properties, and click on the Defragment option in the Tools tab) or a third-party program like Defraggler.

I guess I owe Apple an apolology… I learned that Chrome is based on the WebKit framework, which is an Apple project that is open standard to all developers.  Chrome actually removed some of the extra cool effects that Apple included so that it would be a more lightweight web browser.  Safari was the slowest browser on my old computer which had a 32-bit Windows (Vista) operating system running on a 1.2 GHz CPU with only 2 GB of RAM.  Now, I have a 64-bit Mac OS X Snow Leopard operating system running on a 2.4 GHz CPU with 4 GB of RAM.  Safari opens to my “Top Sites” well within 2 seconds… and that’s from a cold start!

Another thing I’d just like to throw out there: I’ve been using iPhone 4 for a while now, and I have not had any problems whatsoever with reception or “Antennagap” (or whatever the sue-happy people are calling it).  I actually get better reception now than I did with my iPhone 3G.  Bottom-line, the iPhone 4 is a vastly superior smartphone in my opinion.

I must say that I am very pleased with what Apple has been doing recently: the iPad, iPhone 4, Unibody MacBook Pro, Mac Mini, etc.  My friends tell me that it would be extremely ironic if I start working for Apple once I graduate.  To be honest, I’m actually considering it…