Guide

Code

Introduction

This is a guide to maintain a consistent and industry stand coding practices.

Naming conventions

Variables

  • Variable names must be short, descriptive, predictable and snake_cased

Wrong Examples:

$temp_name = "John";
$my_name = "John";
$n1 = "John";
$var = "John";
$n = "John";
$na = "John";
$tempName= "John";
$firstName= "John";
$FirstName= "John";
$getFirstName= "John";
$getfirstname= "John";
$get_first_name= "John";

Correct Examples:

$first_name = "John";
$last_name = "Leo";
$amount = 34;
$price = 643;
$total = 800;

Constants

  • Constants must be short, meaningful, descriptive and in SCREAMING_SNAKE_CASE
    • SCREAMING_SNAKE_CASE:
      • snake_case but with all capital letters
      • 2 words are joined with underscore (_)

Wrong Examples:

define('db_HOST', 'localhost'); 
define('DBUSER', 'db_user'); 
define('DB_pASS', 'password$%@#');
define('db_name', 'db_app');

Correct Examples:

define('DB_HOST', 'localhost'); 
define('DB_USER', 'db_user'); 
define('DB_PASS', 'password$%@#');
define('DB_NAME', 'db_app');

Functions

  • Function/Method names must be short, meaningful, predictable and camelCased

Wrong Examples:

function GetUrl(){};
function Get_Url(){};
function get_Url(){};
function get_Url(){};
function get_url(){};
function geturl(){};
function getu(){};
function namesList(){};
function namesList(){};

Correct Examples:

function getFirstName(){};
function getName(){};
function setName(){};
function storeName(){};

Classes

  • Class manes must be meaningful, singlular and PascalCased.

Wrong Examples:

class cart_total(){};
function cartTotal(){};
function cart_Total(){};
function Carttotal(){};
function Cart_total(){};

Correct Examples:

function CartTotal(){};
function User(){};
function Role(){};

Controllers

  • Controller names must be meaningful, singular and have Controller suffix.
  • Controllers for page must be named after the page
  • Controllers for resources must be named after the page

Bad Examples

ArticlePageController.php
ArticlesController.php
article.php

Correct Example

ArticleController.php

Model

  • A model name should be 'singular,PascalCase/CapitalCase` and should describe the table it is representing.

Bad Examples

customer_roles
customerRoles
CustomerRoles

Correct Example

CustomerRole

Table

  • Table name must be snake_case and plural.

Bad Examples

article_comment, 
articleComments

Correct Example

article_comments

Table Column names

  • Table Column names must be snake_case without model name

Bad Examples

MetaTitle 
article_meta_title

Correct Examples

meta_title

HTTP Request - JSON Response

Each function or method or api must return response in following format:

Success Response

{
  "success": true,
  "messages": ["Action was successful.", "Add more records."],
  "data": {
    "user": {
      "id": 1,
      "name": "John"
    },
    "articles": [
      {
        "id": 1,
        "title": "Article 1"
      },
      {
        "id": 2,
        "title": "Article 2"
      }
    ]
  }
}

Fail Response

{
  "success": false,
  "errors": ["Something went wrong.", "Try again."]

}

Fail response with respect to particular fields

The details key is utilized for failed response to provide a comprehensive error message.

{
  "success": false,
  "errors": ["Fill required fields."],
  "details": {
    "email": [
      "The email field is required."
    ],
    "password": [
      "The password field is required."
    ]
  }

}

Partial success response

{
  "success": false,
  "errors": ["10 records have invalid data."],
  "messages": ["10 new records are successfully saved."],
  "data": {
    "user": {
      "id": 1,
      "name": "John"
    }
  }
}

Optional Response Variables

{
  "hint": "Details to debug the response. Eg: role with slug 'admin' does note exist.",
  "code": 404,
  "meta": {}
}

Reference URLs

We took inspiration from following articles:

  1. https://jsonapi.org/format/
  2. https://api-docs.freewheel.tv/beeswax/docs/api-requests-and-responses
  3. https://medium.com/@bojanmajed/standard-json-api-response-format-c6c1aabcaa6d
  4. https://docs.oasis-open.org/odata/odata-json-format/v4.0/errata02/os/odata-json-format-v4.0-errata02-os-complete.html#_Toc403940655
  5. https://laravel.com/docs/11.x/validation#validation-error-response-format

Copyright © 2024