A starter PHP project with many services and features pre-configured.
The things this project provides or does includes:
For more details, see the section Explanation of Features, below.
To get started, export your GitHub personal access token and then create a new project.
$ export GITHUB_TOKEN='...' $ export APPVEYOR_TOKEN='...' # Optional $ export SCRUTINIZER_TOKEN='...' # Optional $ composer create-project g1a/starter my-new-project
The new project will be owned by the currently-authenticated user. If you would like to create a new project in an organization instead, then set the
GITHUB_ORG environment variable.
$ export GITHUB_ORG='my-github-username-or-org'
The new project will work only with php 7.1 and later. If you need to use an earlier version of php (as far back as php 5.5), then instead run:
$ composer create-project g1a/starter my-new-project:^1
Once the new project is created, automated scripts will customize it and set up a number of serivces. See the section Description of Features below for more information. Once the scripts have finished running, you may customize your README file and start coding!
Before you begin, make sure that the Travis CLI tool has been installed on your system.
Access Token Generation
Generating and exporting a personal access token for the services below is recommended, as doing this will allow the post-create-project scripts to configure and enable these services automatically.
|Export||Token Generation URL|
|exoirt GITHUB_TOKEN='...'||Generate GitHub token|
|export APPVEYOR_TOKEN='...'||Generate Appveyor token|
|export SCRUTINIZER_TOKEN='...'||Generate Scrutinizer token|
Manual Service Configuration
If the personal access token for these services is not set up, then the service may be manually configured later. In addition, this project is also configured for use with Packagist, Dependencies.io and Coveralls; these services only need to be manually authorized through their web interface to enable them for projects created with this template.
Follow the links in the table below to configure the services you would like to use.
|Feature||Manual Setup URL|
|Collaborative repository||Create GitHub project|
|Linux permutation testing||Enable Travis CI|
|Windows testing||Enable Appveyor CI|
|Static analysis||Enable Scrutinizer CI|
|Code coverage||Enable Coveralls|
|Package manager||Register with Packagist|
|Dependency updates||Enable Dependencies.io|
Explanation of Features
composer create-project command runs to create your new project from the templates provided, a GitHub project will automatically be created, and your code will automatically be pushed up.
In order for this to work, you must define a
GITHUB_TOKEN environment variable as described in the usage section.
Your new project will be set up with the outline for a project README, complete with status badges, ready to be customized. Follow the instructions provided in your new project to complete the customization steps.
Travis CI is a testing service that will automatically run your unit tests every time a commit is pushed up to GitHub. Your new project will be automatically configured to run tests on Travis. Travis can authenticate using the
GITHUB_TOKEN environment variable you already defined, so no extra credentials need to be declared for this feature to work.
Appveyor Windows testing
Appveyor is a testing service that will automatically run your unit tests on a Windows environment. If you define an environment variable
APPVEYOR_TOKEN as described in Access Token Generation above, then Appveyor will be configured to run your tests on every commit. If you do not provide authentication credentals for Appveyor, then the customization instructions for your project will include a link that you may use to turn on this service. Everything is configured for you; authenticating with Appveyor is all that is required.
Scrutinizer static analysis
Scrutinizer CI is a service that will perform static analysis of your project on every commit. If you define an environment variable
SCRUTINIZER_TOKEN as described in Access Token Generation above, then Scrutinizer will be configured to analyze your code on every commit. If you do not provide authentication credentals for Scrutinizer, then the customization instructions for your project will include a link that you may use to turn on this service. Everything is configured for you; authenticating with Scrutinizer is all that is required.
Coveralls code coverage
Coveralls is a code-coverage tracking tool. Your new project is configured to collect code coverage statistics whenever your phpunit tests are run. Coveralls does not provide an API to enable project tracking, but the customization instructions for your project includes a link that you can click authenitcate with Coverals and enable coverage tracking.
Packagist code distribution
Packagist is the main repository for Composer projects. The customization instructions for your project includes a link you may follow to register your project in this repository.
Dependencies.io is a service that will automate dependency updates for your project. The customization instructions for your project includes a link to authenticate with dependencies.io; if you enable this service, then a pull request will be created on your project automatically every time any of your Composer dependencies publish a new release.
Data-driven unit test examples
Your new project comes with a trivial
Example class with tests that demonstrate the phpunit @dataProvider feature.
Test matrix for PHP 5.6 - 7.2
Phpunit 6.x is required to test PHP 7.2, but phpunit 5.x is required to test PHP 5.6 and earlier. Your new project will be set up to use phpunit 6.x when running Travis tests on PHP 7.0 and later, and will fall back to using phpunit 5.x when using PHP version earlier than PHP 7.0.
This functionality is provided using the Composer test scenarios project.
PSR-2 checks and PHP linting
In addition to providing unit tests with phpunit, your new project will also automatically contain style checks for PSR-2 coding convnetions, and will lint your code for syntax errors and other problems.
These features may be accessed via
composer cs and
composer lint commands, respectively. A .editorconfig file is provided pre-configured to maintain PSR-2 coventions in editors that support this feature.
GitHub contributing and issue templates
GitHub has a feature that allows projects to define pull request and issue templates which will be presented to users when a new issue or pull request is opened. Also, a contributing document can be provided to explain project conventions to new users.
Starter versions for all of these files are automatically added to your new project, and may be customized as needed. By default, the CONTRIBUTING.md file is added to the project root for better visiblity, but you may move it to the .github directory if you prefer.
Dependency license information
Every time you run
composer update, the license information for all of your dependencies will be automatically appended to your LICENSE file. This will allow users interested in your project to quickly ascertain whether the licenses for your dependencies are compatible. This function is provided by the Composer test scenarios project.
Automatically update copyright year
Whenver your dependency license information is updated, the Copyright year for your project will also be adjusted if necessary, so that your Copyright notice will always include the year of the most recent commit.
Your project includes a script
composer release that will automatically tag your project and create a release on GitHub. The VERSION file is automatically updated for you.
Typically, your VERSION file should be set to the next release of your project, followed by
-dev. For example, if the most recent release of your project is
0.1.0, then your VERSION file should contain
composer release script will automatically remove the
-dev before making the release, and once done will increment the patch release by one and replace the
-dev on the end. To update to the next minor release, change your VERSION file to
0.2.0-dev and run
composer release. Once completed, the VERSION file will then read
If you followed the customization instructions to automatically attach your phar to every release, then your phar releases will report stable versions, and your locally-build phars will report
Note that this simple release script does not support
beta and other SemVer pre-release designations.
Your project will be set up to build a commandline tool, and also includes commands to package it as a phar using the humbug/box project. If your project is a library, you might still wish to include a commandline tool to provide ad-hoc usage to your library functions, either for testing purposes, or perhaps to directly edit any data stores managed by your library. The commandline tool dependencies are declared in the
require-dev section, so they will not be pulled in when your project is included as the dependency of some other project.
If you do not want the commandline tool, simply delete the directories
tests/ExampleCommandsTest.php, and also remove the
phar:* commands in your composer.json file, and the files
Auto-deploy phar on GitHub
The customization instructions for your project include a single command you may run to automatically set up auto-deployment of your project's phar with every GitHub release.
If you are just going to be using the commandline tool for ad-hoc testing, and you do not want to build a phar, then you can move the
consolidation/Robo project from
Phar self:update command
Users who download your phar file from GitHub may obtain the most recent version available by running the
self:update command, which is automatically provided in your new project.
composer.json file included in the project pre-configures a few settings for convenience:
optimize-autoloader: Creates larger autoload files that find classes more quickly
sort-packages: Keeps the list of packages in alphabetic order
platform:php: Ensures that Composer will only select packages that are compatible with the stated minimum PHP version.
Optimized Composer dist releases
Your project's .gitattributes file comes pre-configured to exclude unnecessary files in Composer
Your project will automatically read in a configuration file in yaml format that you may use for providing command option default values and storing other user-overridable settings. See consolidation/config for more information.
Please read CONTRIBUTING.md for details on the process for submitting pull requests to us.
This project is licensed under the MIT License - see the LICENSE file for details.