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.
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 |
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 |
After the 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 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 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 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 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.
Your new project comes with a trivial Example class with tests that demonstrate the phpunit @dataProvider feature.
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.
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 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.
Your project will be set up by default to be offered under the MIT Open-Source license. You may change this by editing your composer.json and LICENSE files.
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.
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 0.1.1-dev. The 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 0.2.1-dev.
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 -dev versions.
Note that this simple release script does not support alpha, 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 src/Cli and tests/ExampleCommandsTest.php, and also remove the phar:* commands in your composer.json file, and the files example and box.json.dist.
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 require to require-dev.
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.
The composer.json file included in the project pre-configures a few settings for convenience:
optimize-autoloader: Creates larger autoload files that find classes more quicklysort-packages: Keeps the list of packages in alphabetic orderplatform:php: Ensures that Composer will only select packages that are compatible with the stated minimum PHP version.
Your project's .gitattributes file comes pre-configured to exclude unnecessary files in Composer dist releases.
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.
- This project makes heavy use of configuration techniques and code from Drush, Robo PHP and other Consolidation projects.
- The KnpLabs github-api and guzzle made the API calls done by this project very easy.