Naming Convention
Table of contents
Loading...Root-level directories
From php-pds/skeleton
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/ |
General files and folders outside src/
- All filenames SHOULD be lowercase
file.ext
- All words of filenames SHOULD be separated by hyphens
file-name.ext
- It SHOULD be tried to avoid multi-worded folders but if there are, they MUST be all lowercase
and separated by hyphens
folder-name
Backend project files and folders in src/
- Folder and files MUST be in PascalCase format. Starting with an uppercase and each word separated by an uppercase.
- Action classes MUST end with the word Action:
LoginAction.php
- Service classes are do-er classes and MUST end with an agent noun and NOT contain the word "Service":
UserCreator.php
. Generic names such as "Manager" or "Handler" should be avoided. - Repository classes MUST end with the word Repository and be named after their according
service class if there is one. E.g.:
UserCreatorRepository.php
- Exception classes MUST end with the word Exception:
InvalidCredentialsException.php
- Middlewares MUST end with the word Middleware:
UserAuthenticationMiddleware.php
- Data Transfer Objects (DTO)
- DTOs that are
designed to contain values of a specific item or resource such as a database table
should be named after it with the suffix Data:
UserData.php
. - Result-objects
which contain data for a specific use-case MUST end with Result:
UserReadResult.php
. - Collection of Data objects
with optional additional attributes. MUST end with ResultCollection:
UserListResultCollection.php
.
- DTOs that are
designed to contain values of a specific item or resource such as a database table
should be named after it with the suffix Data:
Actions
Please see Naming Action classes.
Templates
- Templates that are rendered must end with PHP MUST end with
.html.php
: e.g.login-page.html.php
. - Email templates, PDF and other views that will be rendered into the respective format MUST
be in a respective sub folder and end with
.[format].php
e.g.templates/authentication/email/password-reset.email.php
ortemplates/[module]/pdf/pdf-template.pdf.php
HTML elements
- IDs and class name words MUST be separated by hyphens:
class-name
- Form
name
attribute words MUST be separated by an underscore and MUST be the same as the database column name:name="column_name"
.
Tests
- Folder and files MUST be in PascalCase format - starting with an uppercase and each word separated by an uppercase.
- Test classes names MUST contain the name of the class under test or the
Action class for integration tests and end with the word Test:
Unit test:ClientCreatorTest.php
, Integration test:ClientCreatorActionTest.php
- Fixtures MUST end with the word Fixture:
ClientFixture.php
- Provider MUST end with the word Provider:
ClientProvider.php
- Helper Traits MUST end with TestTrait:
AppTestTrait.php
Test functions
- Unit test functions MUST start with the word test followed by the name of the
function under test and if a function is tested multiple times,
additional info can be appended to the test function name in camel case:
testFunctionUnderTest()
,testFunctionUnderTestAdditionalInfo()
. - Integration test functions MUST start with test and describe the use case which
is being tested and additional info can be added in camel case
e.g.
testUserSubmitCreateAuthorization()
,testUserListUnauthenticated()
.
Providers
Providers are in the folder "Provider" at the root of
the /tests
folder. The same providers may be used by both unit and integration tests.
Each are in sub folders with the module name.
All providers MUST end with Provider: ClientCreateProvider
.
Provider functions may end with the word Provider, Cases or Values depending on the type of provider and preference of the developer.
Fixtures
Fixtures
are in the tests/Fixture
folder and the class name MUST end with Fixture: UserFixture.php
.
Fixtures MUST implement the TestTraits\Interface\FixtureInterface
.
Database
- Databases and table names MUST be all lower case and words separated by underscores
- The test database name is the same as default database but with the "test" keyword added at the end
separated by an underscore:
slim_example_project_test
Standard API JSON response format
Success
Note: mandatory "data"
(null
if nothing)
{
"status": "success",
"data": {
"posts": [
{
"id": 1,
"title": "A blog post",
"body": "Some useful content"
},
{
"id": 2,
"title": "Another blog post",
"body": "More content"
}
]
}
}
Error
Note: "data"
is not mandatory but always welcome.
Note 2: HTTP Code also in the response body would be overkill as we have already the information from the HTTP response.
{
"status": "error",
"message": "Validation error",
"data": {
"errors": {
"first_name": ["Minimum length is 2"],
"email": ["Invalid email"]
}
}
}
Warning
There is no warning entry in the jsend documentation, but I find it useful sometimes.
{
"status": "warming",
"message": "User wasn't updated"
}
References: