pds/skeleton
This publication describes a standard filesystem skeleton suitable for all PHP packages.
Please see https://github.com/php-pds/skeleton_research for background information.
Command-line tools for validating or generating PDS conform packages which are included with this standard are documented here.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this publication are to be interpreted as described in RFC 2119.
Summary
A package MUST use these names for these root-level directories:
| If a package has a root-level directory for ... | ... then it MUST be named: |
|---|---|
| command-line executables | bin/ |
| configuration files | config/ |
| documentation files | docs/ |
| web server files | public/ |
| other resource files | resources/ |
| PHP source code | src/ |
| test code | tests/ |
A package MUST use these names for these root-level files:
| If a package has a root-level file for ... | ... then it MUST be named: |
|---|---|
| a log of changes between releases | CHANGELOG(.*) |
| guidelines for contributors | CONTRIBUTING(.*) |
| licensing information | LICENSE(.*) |
| information about the package itself | README(.*) |
A package SHOULD include a root-level file indicating the licensing and copyright terms of the package contents.
Root-Level Directories
bin/
If the package provides a root-level directory for command-line executable
files, it MUST be named bin/.
This publication does not otherwise define the structure and contents of the directory.
config/
If the package provides a root-level directory for configuration files, it MUST
be named config/.
This publication does not otherwise define the structure and contents of the directory.
docs/
If the package provides a root-level directory for documentation files, it MUST
be named docs/.
This publication does not otherwise define the structure and contents of the directory.
public/
If the package provides a root-level directory for web server files, it MUST be
named public/.
This publication does not otherwise define the structure and contents of the directory.
N.b.: This directory MAY be intended as a web server document root. Alternatively, it MAY be that the files will be served dynamically via other code, copied or symlinked to the "real" document root, or otherwise managed so that they become publicly available on the web.
resources/
If the package provides a root-level directory for other resource files, it MUST
be named resources/.
This publication does not otherwise define the structure and contents of the directory.
src/
If the package provides a root-level directory for PHP source code files, it
MUST be named src/.
This publication does not otherwise define the structure and contents of the directory.
tests/
If the package provides a root-level directory for test files, it MUST be named
tests/.
This publication does not otherwise define the structure and contents of the directory.
Other Directories
The package MAY contain other root-level directories for purposes not described by this publication.
This publication does not define the structure and contents of the other root-level directories.
Root-Level Files
CHANGELOG
If the package provides a root-level file with a list of changes since the last
release or version, it MUST be named CHANGELOG.
It MAY have a lowercase filename extension indicating the file format.
This publication does not otherwise define the structure and contents of the file.
CONTRIBUTING
If the package provides a root-level file that describes how to contribute to
the package, it MUST be named CONTRIBUTING.
It MAY have a lowercase filename extension indicating the file format.
This publication does not otherwise define the structure and contents of the file.
LICENSE
Whereas package consumers might be in violation of copyright law when copying unlicensed intellectual property, the package SHOULD include a root-level file indicating the licensing and copyright terms of the package contents.
If the package provides a root-level file indicating the licensing and copyright
terms of the package contents, it MUST be named LICENSE.
It MAY have a lowercase filename extension indicating the file format.
This publication does not otherwise define the structure and contents of the file.
README
If the package provides a root-level file with information about the package
itself, it MUST be named README.
It MAY have a lowercase filename extension indicating the file format.
This publication does not otherwise define the structure and contents of the file.
Other Files
The package MAY contain other root-level files for purposes not described in this publication.
This publication does not define the structure and contents of the other root-level files.