spoom-php/core

Core extension of the Spoom Framework

Framework

The framework is a single class with some constants, internal log/reporting level handling and an extension search feature. This class main function is the library importer with autoload support. Any other feature is provided by extensions. The framework MUST be initialized before use. So in the bootstrap file you MUST call the Framework::setup() to initialize the framework (autoloader, default levels and some checks). For the method you can specify a main function that runs after the initialization. The default index.php has an example for this., _(*1)

Importer

The library import is accessible with the \Framework::import() method. This method use only one parameter that MUST be the fully qualified name of the class that needs to be imported. This method's result is true if the given class is exists after the import. The importer main purpose is to load extension's library classes but it also supports custom namespace sources that is compatible with PSR-4. Example for extensions:, _(*2)

\<Package>(\<Name>(\<Feature>)?)?(\<Namespaces>)*\<Class(Fragment)*>, _(*3)

This "defines" the following directory structure and filename:, _(*4)

/extension/<package>(-<name>)(-<feature>)?)?/library/(<namespaces>/)*<class>(<fragment>)*.php, _(*5)

Directory structure (including the filename) SHOULD be lowercase, and the namespaces for that MAY have ucfirst. The importer also supports the mixed lettercase structures as well (in case-sensitive environment), but not recommended. Examples:, _(*6)

The \SamplE\FoO\bAr\ClassName class can be in: - /extension/sample/library/foo/bar/classname.php - /extension/sample/library/foo/bar/ClassName.php - /extension/sample/library/FoO/bAr/ClassName.php - /custom/sample/foo/bar/classname.php - /custom/sample/foo/bar/ClassName.php - /custom/samplE/FoO/bAr/ClassName.php, _(*7)

Class nesting

The fragment parts can be ignored in the file name, so you could put more class in one file. For example: Define a trait and an interface for it may be in the same file, or custom exception classes used by only one class... etc. This nested classes' name MUST be started with the file name that contains the class, and the remain part MUST be separated with an uppercase letter. For example the \Sample\Foo\ClassNameException class' files can be:, _(*8)

• /extension/sample/library/foo/class.php
• /extension/sample/library/foo/classname.php
• /extension/sample/library/foo/classnameexception.php

Custom roots

The importer supports custom roots for namespaces. Custom root can be added with the Framework::connect() method where you MUST specify the namespace and this namespace's root path. For example:, _(*9)

 \Framework::connect('\Sample\Foo\', '/custom/location');
 // after that the '\Sample\Foo\Bar\Class' will be loaded from '/custom/location/bar/class.php'

The nesting and letter case supports also applied to the custom roots. The custom root lookup is executed before the standard extension library lookup, so be careful of the namespace you connect., _(*10)

Development

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119., _(*11)

This will apply to the framework and all extensions either!, _(*12)

Coding standard

Code MUST follow the PSR-1 guide with the following modifications:, _(*13)

• Autoloading has support for multiple classes in a file
• Property names MUST be in $under_score format
• Property accessor and mutator SHOULD defined with the 'get|is*' and 'set*()' methods (for interface support). It's RECOMMENDED to also have magic access to this properties through this methods

Exception handling

• The exceptions in the code SHOULD never be returned by a method or function. You MUST throw an exception, or store it in a class ->exception or ->collector property!

Coding style

The code MUST follow the PSR-2 guide with the following modifications and extras:, _(*14)

• Code MUST use 2 spaces for indenting instead of tabs
• Opening braces for classes MUST go on the same line, and closing braces MUST go on the next line after the body
• Opening braces for methods MUST go on the same line, and closing braces MUST go on the next line after the body
• The abstract, final and static MUST be declared after the visibility
• Control structure keywords, method and function calls MUST NOT have one space after them
• Opening parentheses for control structures MUST have a space after them, and closing parentheses for control structures MUST have a space before
• Lists of implements SHOULD NOT be split across multiple lines
• Argument lists SHOULD NOT be split across multiple lines

• When making a method or function call, there MUST be a space after the opening parenthesis, and there MUST be a space before the closing parenthesis, _(*15)

• FIXME and TODO for class or method MUST be placed after the description in the PHPDoc, _(*16)

Language

All elements in the code (variables-, classes-, methods-, comments...etc) and readme files MUST be written in English (US) language. The documentation MAY be written in other languages, but an English version of the documentation MUST exists., _(*17)

Versioning

Version numbers MUST follow the Semantic Versioning rules., _(*18)

Git

One commit MUST contains only one extension's changes, but one repository MAY contain more extensions. The branching model MUST follow this "rules", with a little differences:, _(*19)

• The 'develop' branch name MUST be 'development'
• The commits of unfinished features (in any 'feature-*' branch) SHOULD NOT have title. In the main branches ('development' or 'master'...or any other) all commit MUST have a title (including merge commits)
• Avoid unnecessary merge commits from remote update in the main branches
• The commits in the 'master' branch MUST be tagged with the version name, with 'v<version>' format

Commit message format

title, _(*20)

content
type!:description, _(*21)

Types

An ! after the type indicates the compatibility broker changes., _(*22)

• fix
• refactor
• deprecated
• remove
• update
• new
• other
• ...

Example

This is the commit title, _(*23)

This is a longer description for the commit changes, and MUST be in one line
fix: This is one change description that was a fix
update: This is an other change description that was an update, _(*24)