internals.md

Internals

Development dependencies

In order to work on ChillDevFileManagerBundle you need to install a few more things than basic dependencies:

• phpunit/phpunit - for running tests;
• squizlabs/php_codesniffer - for coding style rules compilance checking;
• satooshi/php-coveralls - for integration with Coveralls;
• sebastian/phpcpd - copy-paste detector for duplicated code parts;
• phpmd/phpmd - static code analysis tool to enforce writing good code;
• phpDocumentor - for generating API documentation.

Most of them are defined in composer.json file, so running composer.phar --dev install will do the job. The only things you need to install manualy is phpDocumentor which does not have a valid Composer package yet. But you probably won't need phpDocumentor, since it's only used for publishing documentation. If you want to use it anyway, you will also need php-xsl extension.

Coding style

Currently we follow PSR-2 coding rules and additionally rules defined in rules.xml file for PHP Mess Detector.

Makefile targets

This project utilizes make as primary build automation tool. It's Makefile defines following tasks:

• init - initializes project by loading all Git submodules and installing dependencies with Composer;
• update - updates dependencies with Composer;
• check - performs syntax checking on all project files using php -l;
• lint - checks coding standards compliance with PHP_CodeSniffer and detects duplicated code parts with phpcpd;
• analyse - performs static code analysis with PHP Mess Detector;
• tests - runs all unit tests and generate coverage report with phpUnit;
• documentation - generates project API documentation with phpDocumentor.

There are also meta-targets:

• all which executes check, lint, analyse, tests and documentation subsequently (it is run by default);
• ci which executes check, lint, analyse and tests (set of QA targets).

Additionally, there is available coveralls step which uploads tests coverage statistics to Coveralls, but it shouldn't be used outside of Travis-CI.

Continous integration

This project uses Travis-CI as it's continous intergation environment. It is configured to evaluate check, lint, analyse and tests targets to ensure code matches quality standards.

Templating engine

To simplify things we use @Template annotation from SensioFrameworkExtraBundle. But there is one problem with this annotation - while it drops template reference from code it makes that implicit reference quite costant. Mainly it makes it impossible to switch between templating engines (if controller uses Twig and your application PHP templates you are doomed). That's why we use ChillDevProxyTemplatingBundle - it's DefaultEngine allows us to write simply:

    /**
     * @Template(engine="default")
     */
    public function fooAction()
    {
        // action code here
        return $viewData;
    }

Why not…

…use mount-style flow

Because it would be hard to apply. Mounts within web manager would not be applied to real filesystem so it could lead to conflicts. Imagine you use /var/www/ as your root and define /var/log/nginx/ to be mounted as /logs/. If you then create /var/www/logs/ we could have a problem to solve - so at least for now it's better to avoid the problem as we have much more in ToDo list.

…use Gaufrette

Because it works like a key-value store. It lacks tree traversing flow. It's nice if you need to support single directory abstraction, but not for file-managing purpose.

…provide filesystem abstraction interface

There was a plan to do that, but eventually we considered it as a bloat-feature. All I/O and FS operations map to PHP high-level API that ifself provides abstraction through stream wrappers. There would be no point in handling all I/O on our own and write own adapters for something that is already abstracted in underlying API.