3. Making modules perfect

#How to create awesome SamsonPHP module This guide will tell you best practices for creating SamsonPHP external modules and how to make them really awesome, beautifull and really usefull.

Module creation

All SamsonPHP meet next requirenments:

• All modules must be developed based on TDD principle, so you have to keep in mind that tests are in first place.
• All modules must follow PSR-2 code style format.
• All modules must follow PSR-0 class naming convention. With use PHPCodeSniffer for automatic code style analysis.
• All modules must fully documented, after tests are completed a full documentation and examples guide must be created. We use Markdown syntax on writing module docs.
• All modules(opensource) has to be easy accessible, for this purposes we use Packagist.

All SamsonPHP modules must follow next project structure:

• tests
• src - Source code root folder
• docs - Module documentation folder
• composer.json - Project description and dependecy configuration via Composer.
• readme.md - Introductory module documentation file. We advice you to link this file with the rest of documentation /docs/ via relative links.
• .travis.yml - travis-ci.org configuration file.
• .scrutinizer.yml - scrutinizer-ci.com configuration file.
• phpunit.xml - PHPUnit Unit testing configuration file.
• phpunit.php - PHPUnit bootstrap file, used mostly to require composer autoload file.
• .gitignore - If you are here than you probably know what is it.

Open-source modules

First of all SamsonPHP modules are open-source, this gives ability to better maintain code and use awesome features such as:

• Continuos integration - travis-ci.org or scrutinizer-ci.com
• Code coverage testing - coveralls.io or scrutinizer-ci.com
• Code quality analisys - codeclimate.com or scrutinizer-ci.com

All this awesome absolutely free(for open-source) services gives you ability to create best possible code ever!

If you develop private, non open-source SamsonPHP modules you are free to use commercial versions of products described above, but we still advice you to do this!

Automating module development process

To do this we assist that you should write unit tests for it, if you cannot write unit test for some reason it means that your code is very coupled and has unscallable structure inside it, so first of all you must think about making it more independent, more significant and more lossely coupled with other code, only meeting this requirenments will give you ability to write tests for it.

Your main goal is to write unit tests that covers 99.9% of your code. If you cannot do it - change your code signifficantly. Secondary goal is to get 10.0 points in code quality.

For simplifing testing process we advice you to use travis-ci.org or scrutinizer-ci.com services.

This services automatically adds web-hooks to your repo and performs everything automatically on your push.

This services are very similar at build stage so we advice you to use both of them. For now, scrutinizer has some more benefits.

Scrutinizer-ci.com configuration

This service is configured via .scrutinizer.yml file which me placed in your web-application/module project root. This is default Scrutinizer-CI configuration file that almost perfectly fits any SamsonPHP module:

tools:
    php_sim: true
    php_pdepend: true
    php_analyzer: true
    php_cs_fixer:
            config: { level: psr2 } # or psr1 if you would just like to get fixes for PSR1
    php_code_sniffer:
            config:
                standard: "PSR2"

filter:
    excluded_paths:
        - 'tests/*'

build:
    environment:
        php:
            version: 5.5

travis-ci.org configuration

This is default Travis-CI configuration file that almost perfectly fits any SamsonPHP module:

language: php

php:
  - 5.3
  - 5.5

before_script:
  - travis_retry composer self-update
  - travis_retry composer install --prefer-dist --no-interaction

script:
 - phpunit --verbose --debug --coverage-clover=coverage.clover

after_script:
 - wget https://scrutinizer-ci.com/ocular.phar
 - php ocular.phar code-coverage:upload --format=php-clover coverage.clover

This configuration includes fully automatic integration with all opensource services described above, the only thing is left for you is to connect your repo with that services.

After you have connected your repo we advice you to use another awesome feature - badges, this is automatic notification about your module which is shown via your readme.md which is by default shown in your repo index page. So you and everyone knows everything about module status. This is example of all main usefull badges that we advice to you, feel free to change/add/delete any if you want.

All you have to do is change repo name(in our example this is samsonos/php_fs) to yours.

#YOUR MODULE NAME
[![Latest Stable Version](https://poser.pugx.org/samsonos/php_fs/v/stable.svg)](https://packagist.org/packages/samsonos/php_fs) 
[![Build Status](https://travis-ci.org/samsonos/php_fs.png)](https://travis-ci.org/samsonos/php_fs) 
[![Code Coverage](https://scrutinizer-ci.com/g/samsonos/php_fs/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/samsonos/php_fs/?branch=master)
[![Code Climate](https://codeclimate.com/github/samsonos/php_fs/badges/gpa.svg)](https://codeclimate.com/github/samsonos/php_fs) 
[![Total Downloads](https://poser.pugx.org/samsonos/php_fs/downloads.svg)](https://packagist.org/packages/samsonos/php_fs)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/samsonos/php_fs/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/samsonos/php_fs/?branch=master)

Steps to make perfect SamsonPHP module

• Create repo at (github.com)[http://github.com] or (bitbucket.org)[http://bitbucket.org]
• Create project structure described above
• Add .scrutinizer.yml as above
• Add .travis.yml as above
• Add repo to scrutinizer-ci.com
• Add repo to travis-ci.org
• Add readme.md as above
• Add composer.json with package name, author, description, keywords and dependencies
• Add your repo to Packagist
• Create a web-hook for Packagist in your repo settings at (github.com)[http://github.com] or (bitbucket.org)[http://bitbucket.org]
• Add your code!
• Create tests for it!
• Make your first push
• Check if your badges are working well
• Get 100% code coverage and 10.0 code quality mark
• When all above steps are finished - Create a release.