Naming Convention

Table of contents

Root-level directories

From php-pds/skeleton

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.

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 or templates/[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).

There is no standard convention when the key is composed of multiple words. My personal choice is camelCase according to Google recommendation.

{
  "status": "success",
  "data": {
    "postList": [
      {
        "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": {
      "firstName": ["Minimum length is 2"],
      "email": ["Invalid email"]
    }
  }
}

Warning

There is no warning entry in the jsend documentation, but I find it useful sometimes.

{
  "status": "warning",
  "message": "User wasn't updated"
}

References:

• https://github.com/omniti-labs/jsend
• https://stackoverflow.com/questions/12806386/is-there-any-standard-for-json-api-response-format