Content

• Run the website locally
• Add a project
• Send a Pull Request

Run the website locally

• Install docker-compose through Docker CE
• Run the Jekyll container by running the terminal command docker-compose up
• Open the webpage at http://0.0.0.0:4000 or http://127.0.0.1:4000
• Keep track of Jekyll errors by running the terminal command docker-compose logs -f

Add a project

If you want to add your own project, the easiest way is probably to copy the _draft.md page from the __projects directory.

Most of the *.md files are named according to their short name or their command, but the choice might be yours.

Any file in that directory consists of two parts:

• the Jekyll Front Matter
• the description

Jekyll Front Matter

This is basically valid YAML in between triple-dashed lines.

Basic project information

Layout

layout: string 'project'

Jekyll's layout field. This is a required field, and should always be 'project'.

Title

title: string title

The official name of the project. This is a required field, and will mostly be the main title of the GitHub's README.

This field should also be used to start the description of the project (see description).

Tags

tags: string[] tags

A list of tags describing this project. This is a required field, as the tags are being used on the overview page. They provide easy filtering in an ever-growing list. Try to be as specific as possible, while also keeping the amount of new tags down.

Authors

authors: array [object {name: string name, url: string url = nil}]

The author(s) of the project. This is an optional field, but is strongly encouraged for any project that has a publicly available repository. It should be an array of objects with at least a name property.

• name: required
  • The name of the author.
• url: optional
  • The url¹ where the author can be reached.

Companies

companies: array [object {name: string name, url: string url = nil}]

The compan(y/ies) behind the project. This is an optional field, but is strongly encouraged for any project that has a company backing it. It should be an array of objects with at least a name property.

• name: required
  • The name of the company.
• url: optional
  • The url¹ where the company can be reached.

Online resources

Website

website: array [object {url: string url, label: string label = nil}]

The website(s) for the project. This is a required field. It should be an array of objects with at least a url property.

• url: required
  • The url¹ for this website.
• label: optional, discouraged
  • The label for this website.
  • This field will be used to overwrite the visible url on the project detail page.

License

license: array [object {url: string url, label: string label}]

The license(s) for the project. This is a required field for licensed projects. It should be an array of objects with at least a url and a label property.

• url: required
  • The url¹ where this license can be read in full.
• label: required
  • The type of this license. Examples are: BSD 2-clause "Simplified" License, BSD 3, BSD 3-Clause License, BSD 3-clause "New" or "Revised" License, BSD-3-Clause, GNU Affero General Public License, GNU Affero General Public License v3.0, GNU General Public License v2.0, GNU Lesser General Public License v3.0 (LGPL), LGPL-2.1, MIT, MIT License, MIT license, Open Software License version 2.1, The PHP License, The Unlicense.
  • This field will be used to overwrite the visible url on the project detail page.

Terms

terms: array [object {url: string url, label: string label}]

The terms for the project. This is a required field for online services. It should be an array of objects with at least a url and a label property.

• url: required
  • The url¹ where the terms can be read in full.
• label: required
  • The exact name for these terms. Examples are: Terms, Terms Of Service.
  • This field will be used to overwrite the visible url on the project detail page.

Wiki, Docs and/or Demo

wiki: array [object {url: string url, label: string label = nil}]

docs: array [object {url: string url, label: string label = nil}]

demo: array [object {url: string url, label: string label = nil}]

Extra fields for the project. These are all optional fields, but it is highly encouraged to provide them if possible. They should all be an array of objects with at least a url.

• url: required
  • The url¹ where this wiki / documentation / demo can be found.
• label: optional, discouraged
  • The label for this wiki / documentation / demo.
  • This field will be used to overwrite the visible url on the project detail page.

Discoverability

GitHub

github: array [object {name: string name, url: string url = nil}]

The GitHub repositor(y/ies) behind this project. This field is required for projects with a GitHub repository, and should be an array of objects with at least a name.

• name: required
  • The name of the GitHub project. This consists of the GitHub organisation name, a forward slash and the GitHub repository name. The easiest way is probably to check the title on the main page of your GitHub project.
• url: optional, discouraged
  • The url¹ where the GitHub repository can be found.
  • If this property is not provided, the url will be generated as a concatenation of 'https://github.com/' and the name.

Packagist

packagist: array [object {name: string name, url: string url = nil}]

The Packagist package(s) behind this project. This field is required for projects available as a Packagist package, and should be an array of objects with at least a name.

• name: required
  • The name of the Packagist project. This consists of the Packagist organisation name, a forward slash and the Packagist package name. The easiest way is probably to check the title on the main page of your Packagist project.
• url: optional, discouraged
  • The url¹ where the Packagist package can be found.
  • If this property is not provided, the url will be generated as a concatenation of 'https://packagist.org/packages/' and the name.

DockerHub

dockerhub: array [object {name: string name, url: string url = nil}]

The Docker image(s) available on DockerHub for this project. This field is required for projects that have a DockerHub image available. It should be an array of objects with at least a name.

• name: required
  • The name of the DockerHub image. This consists of the DockerHub organisation name, a forward slash and the DockerHub image name. The easiest way is probably to check the title on the main page of your DockerHub page.
• url: optional, discouraged
  • The url¹ where the DockerHub image can be found.
  • If this property is not provided, the url will be generated as a concatenation of 'https://hub.docker.com/r/' and the name.

Installation

Dependencies

dependencies: string[] dependencies = []

A list of dependencies the project relies on, other than PHP itself. Some projects require php extensions enabled, or special libraries added before installing the project. This field is optional.

Composer

composer: object {name: string name = nil, version: mixed version = nil, command: mixed command = nil}

composer-dev: object {name: string name = nil, version: mixed version = nil, command: mixed command = nil}

composer-global: object {name: string name = nil, version: mixed version = nil, command: mixed command = nil}

The Composer package behind this project. These fields are required for any project that can be installed with Composer. They should all be an object with most of the times at least a command property.

• name: optional
  • The name of the Composer package. It will be used as the package name to install.
  • If this property is not provided, it will default to the Packagist name.
• version: optional
  • The version that is needed to install this package.
  • This field is a mixed field, it can be either string version, string[] [string version] or object {string type: string version}.
    • The string or string[] version is useful for specifying that for example dev-master should be required.
    • The object version helps with targeting specific environments: {'PHP 5.6': '0.5.6', 'PHP 7+': '1.0.0'}.
• further-instructions: optional
  • Further instructions can be provided.
• command: optional
  • The command that will be available after installation.
  • This field is a mixed field, it can be either string command, string[] [string command] or object {string type: string command}.
    • The string or string[] option is useful for specifying which commands are available after the installation.
    • The object option helps with mentioning specific actions: {'initiate': 'command', 'run': 'command'}.

Gem

gem: object {name: string name, command: mixed command = nil}

The Gem behind this project. This field is optional, but highly encouraged for any project that can be installed with RubyGems or Bundler.
It should be an object with at least a name property.

• name: required
  • The name of the Gem. It will be used as the name to install.
• further-instructions: optional
  • Further instructions can be provided.
• command: optional, encouraged
  • The command that will be available after installation.
  • This field is a mixed field, it can be either string command, string[] [string command] or object {string type: string command}.
    • The string or string[] option is useful for specifying which commands are available after the installation.
    • The object option helps with mentioning specific actions: {'initiate': 'command', 'run': 'command'}.

Git

git: object {url: string url = nil, update-submodules: boolean update-submodules = false, install-composer-dependencies: boolean install-composer-dependencies = false, command: mixed command = nil}

The Git repository behind this project. This field is optional, but highly encouraged for any project that can be installed from a Git repository. It should be an object with at best at least a command property.

• url: optional, discouraged
  • The url¹ of the Git repository. It will be used as the url to clone.
  • If this property is not provided, it will default to a modified version of the GitHub url.
• update-submodules: optional
  • If the repository needs to initiate any Git submodules, set this to true.
• install-composer-dependencies: optional
  • If the repository needs to install some Composer dependencies, set this to true.
• further-instructions: optional
  • Further instructions can be provided.
• command: optional, encouraged
  • The command that will be available after installation.
  • This field is a mixed field, it can be either string command, string[] [string command] or object {string type: string command}.
    • The string or string[] option is useful for specifying which commands are available after the installation.
    • The object option helps with mentioning specific actions: {'initiate': 'command', 'run': 'command'}.

PHAR

phar: object {url: mixed url}

The PHAR location for this project. This field is optional, but highly encouraged for any project that can be installed as a PHP Archive. It should be an object with a url property.

• url: required
  • The url¹ of the PHAR location. It will be used as the url to download with either wget or curl.
  • This field is a mixed field, it can be either string url, string[] [string url] or object {string type: string url}.
    • The string or string[] option can provide one or more PHAR locations.
    • The object option helps with targeting specific environments: {'PHP 7': 'https://url.to/project'}. It can also be used to provide more context: {'No HTTPS': 'http://url.to/project'}.
• further-instructions: optional
  • Further instructions can be provided.

* Further instructions

further-instructions: object {string instruction: string command}

Further instructions to be executed after installation. This field is available as an optional field for most of the installation options composer, gem, git and phar. Simply add the option to the object to provide further instructions.

• further-instructions: optional
  • A list with steps to run directly after installation, to prepare before first use.
• description: optional
  • The instruction of the step, like "Add the file to your directory".
  • The command for this step, like "mv file directory/file". –>

Description

[{{ page.title }}]({{ page.url | absolute_url }}) is a website that lists many useful PHP QA projects.

<!--more-->

It enlists many well-known as well as lesser known PHP Quality Assurance projects for everyday use.

The description is the part below the Jekyll Front Matter. It consists of two parts, separated by the Jekyll excerpt_separator <!--more-->.

The first part of the description should try to describe the project in one short sentence. This will be the sentence that will be visible on the overview page. Try to use the name of the project somewhere in the beginning, and do it by using this code [{{ page.title }}]({{ page.url | absolute_url }}).

Then add the Jekyll excerpt_separator <!--more-->, and go wild with the longer description that will be completely visible on the detail page.

Send a Pull Request

Fork the phpqa.github.io repository, add your file to the __projects directory, and send us a Pull Request.

Notes

1: YAML requires single quotes around all urls, as the colon in the url will throw it off.