About organizing PHP includes

In PHP, when you need to use a class or a function, you have to require the file that contains that class or function. Most of the time, developers do this using the require_once keyword.

When your application becomes big, you will start wondering what is the best strategy to require all the files.
A common strategy is to write a file typically named load.php and to put all the require_once instructions in that file. This way, in your pages, you require only load.php, and your code will be loaded.

This strategy works great for small projects. However, when you start adding more files, you will realize this has an impact on performances. Requesting more that 200 files to be loaded for each request can place a burden on the PHP interpretor. To avoid this, you can of course require the files only when they are needed, but this strategy puts the burden on the developer and is error-prone.

Hopefully, PHP comes with the magic autoload feature. The autoload feature can trigger a special function each time PHP finds a class that does not seem to exist. Using autoload, we can specify a function that will require the file containing the missing class. This is in a way a lazy loading of classes. One important fact to remember is that autoload is only triggered for classes, not functions.

Organizing your PHP imports with Mouf

Mouf is about proposing a graphical experience with a nice UI to the developer. This is also true when you organize your files: there is a screen for it!

To access this screen, in the Mouf developer interface, just click the Menu > Include PHP files link.
In this screen, you can just click the Add a new file button to add additional files to be included by Mouf.
Click the Save button when you are done.

Now, when you include Mouf.php (using require_once 'Mouf.php'), all the files you selected will be included.

About includes performance

Mouf has an advanced technique to analyze and optimize included files.
Basically, it will look into each file. If the file contains only classes, this file is elected to be autoloaded. Therefore, Mouf will not perform a require_once when you include Mouf.php. Instead, Mouf will wait for the class to be called, and PHP will use the Mouf autoload to load the class.

However, if a file contains a function, the function cannot be autoloaded so Mouf will not select the file for autoloading.

You can see whether a file will be autoloaded or not in the right part of the screen.

When you see the green "autoload" button, this means the file contains only classes and will be autoloaded.
When you see the yellow "no autoload" button, this means Mouf has detected functions and will use the normal require_once mechanism to include the files.

Best practices

Your interest is to put the maximum number of files in "autoload" state.
To do this, our advice is:

• Put each class alone, in its own file
• Files containing classes should not contain any other functions, function calls, global variables, constants, etc...
• Do not use require_once in any of your files. Instead, use Mouf "Include PHP files" feature, and include all your PHP files via this screen.
• Files included should not output anything directly (see this great tutorial for more information)

Advanced optimisation

The analyze of Mouf is detailed and complex, but yet, there are cases when Mouf might take the wrong decision (Mouf might decide a file can be autoloaded, but it can't). This is especially true if you generate classes dynamically using eval. Must developer will tell you that "eval is evil" and that you shall not do such a thing. Yet, this can happen.

If the Mouf analyze takes the wrong decision, you can still decide to overload Mouf default behaviour.

In the "Include PHP files" screen, for the file you want to change the load mode, click the "View details" button.
A box will be opened, with the list of Interfaces, Classes and Functions found in this file. At the top of the box, the drop-down will allow you to select the autoload mode.

• auto-detect: this is the default mode. Mouf will decide automatically whether to use autoload or not.
• force: in this mode, the file will not be included by default and will be autoloaded when a class contained in this file is loaded. Do not use this parameter if your file does not contain any class or interface!
• never: in this mode, the file will always be included via a classic require_once call.