Code - Vaah Docs

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:

Git

Laravel