Asset Structure

Directories and Definitions

The directory structure utilized here partially resembles the directory structure used by the Linux operating system. It is how I structure the PHP products I work on, majority of which are user facing. Not all of the directories below will always be present in every product. The requirements of a product will dictate its directory needs.

• bin – Binaries and other programs, indirectly accessible to the users are placed and executed from here.
• cache – Cache files which improve performance of the product, as well as its interactions with external systems, e.g. API call limits. The directory must be writable by the web server and in most cases owned by it as well. File store in this directory can be deleted at any time without interfering with the product’s normal function.
• data – Files containing reference data, used for normal functions of the products. Longer term data generated by the product or a user. Or serverless databases, e.g. SQLite.
• docs – Product documentation, e.g manual, guides, or any other literature a user might find helpful.
• etc – Holds configuration files. Files are maintained by the product administrator.
• images – A store of images which are not part of the UI templates.
• files – Files for use by users, i.e. downloads.
• log – Log files generated by the products processes, as needed.
• secure – Forms and other pages which require additional user validation. By using a separate directory WebSSO rules are much easier to apply.
• tmp – Temporally files generated by the product mostly for purposes of the product and back-end processes. File store in this directory should be able to be deleted at any time without interfering with the product’s normal function. Though the clean up should be done by the same processes which require the files, thus avoiding any interference from administrators or stale temporally files.
• templates – Files comprising different elements of the UI.
  • images – Images, which are only used as elements of a template.
  • scripts – Scripts, which are only part of a template and serve to provide UI functionality.
  • styles – Style sheets used to control the UI layout.

Security Note: Remember that some of the above directories should not be accessible via the web, e.g. etc, log, and to some extend, depending on the products requirements, data and tmp. It is also a good practice to avoid directory permissions set above 755 (drwxr-xr-x).

Files (headers, definitions, commenting, closing tag …)

Naming Conventions

File Naming Convention

Building block files, i.e. classes, functions, includes etc., are stored in the lib directory, with some exceptions, e.g. templates, config. Unlike some other conventions where files are stored in directories named based on their purpose, minimalism is preferred, but organization is necessary. To make sense of all the files stored in the lib directory a file name is composed of two parts: file content type and PHP element name/purpose.

ContentType.ElementName.php

The former is self-explanatory and allows files to sort nicely when browsing the directory. The latter is used as shortcut to get the class/function name at a glance, without the need to examine the file contents. The file “ElementName” follows the PHP elements naming convention, when appropriate. For readability, hyphens are acceptable to use in place of underscores.

Complex projects will have a different directory structure, e.g. child and grand-child directories, etc.

• action.do-something.php – Action files hold logic which evaluates a user’s actions and accordingly does something, e.g. update objects or call a function.
• class.ClassName.php – Class files store just what they indicate – classes.
• config.something.txt – Configuration files store formated parameters with administrator defined values. This files are parsed by the products internal processes, usually initiated by the inc.environment.php file.
• function.function-name.php (function.function_name.php, function.functionName.php) – A single function, which is reusable in different processes. Or, it is just not part of a large set of function used in a sequence.
• functions.group-purpose.php – Group of functions with similar purpose, used in the same process or used in a sequence, and are not used outside of that process/sequence. By avoiding N include/require calls there is a overall optimization both during development as well as with performance.
• inc.file-pupose.php – General logic like variables, basic processes, sets of include and required calls, etc. Typically anything that is beyond the above file types, but is a building block.
• template.name-purpose.php – Template file, used for the purposes of UI.

Source Code Elements

Below is the source code elements naming convention. It is primarily designed to visually distinguish the different elements when reading the code.

• _private – A visual queue that the variable, class or function are private. Though, I don’t really use it since the “private”, “public” and “protected” declaration keywords exists.
• ClassName – Classes use the UpperCamleCase convention, where the first letter is always a capita letter.
• function_name – Function names are always lower case, and underscores are used to separate words. This is done to visually distinguish them from classes and variables.
• variableName – Variable names use the lowerCamleCase convention, where the first letter is always lower case.
• CONSTANT_NAME – Constants are always upper case, and underscores are used to separate the words to make them easier to read.

Syntax Style

Default Building Blocks

Back to the Coding Conventions.