README

A set of tools to simplify the work of creating backend APIs for your frontend projects. Includes tutorials, patterns and practical examples for creating projects based on REST APIs.

Installation

Download source code and add to your project

<?php
require_once __DIR__ . '/APIlite/src/APIlite.php';

or use composer

composer require tpsoft/apilite

and add to your project

<?php
require __DIR__ . '/vendor/autoload.php';

class YourAPI extends \TPsoft\APIlite\APIlite {

	/**
	 * My first method for greetings.
	 *
	 * @param string $name Your name
	 * @param int $age Your age
	 * @return string Greetings
	 */
	public function myFirstMethod(string $name, int $age): string
	{
		return 'Hi, I`m '.$name.' and I`m '.$age.' years old.';
	}

}

Basic usage

For example, we create an API for calculator. So we create class APIcalculator and store in file test/APIcalculator.php where we defined each actions for API as public method.

<?php

/**
 * Class APIcalculator
 *
 * A calculator class that extends the functionality of TPsoft's APIlite.
 * This class provides basic arithmetic operations and a few additional
 * mathematical functions.
 *
 */

require_once __DIR__ . '/../src/APIlite.php';

class APIcalculator extends \TPsoft\APIlite\APIlite
{

	/**
	 * Add two numbers.
	 * Standard plus operation.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The sum of the two numbers.
	 */
	public function add(float $a, float $b): float
	{
		return $a + $b;
	}

	/**
	 * Subtract two numbers.
	 * Standard minus operation.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The difference of the two numbers.
	 */
	public function subtract(float $a, float $b): float
	{
		return $a - $b;
	}

	/**
	 * Multiply two numbers.
	 * Standard multiplication operation.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The product of the two numbers.
	 */
	public function multiply(float $a, float $b): float
	{
		return $a * $b;
	}

	/**
	 * Divide two numbers.
	 * Standard division operation. Throws an exception if dividing by zero.
	 *
	 * @param float $a The first number.
	 * @param float $b The second number.
	 * @return float The quotient of the two numbers. Throws an exception if dividing by zero.
	 * @throws \Exception If dividing by zero.
	 */
	public function divide(float $a, float $b): float
	{
		if ($b == 0) {
			throw new \Exception('Division by zero');
		}
		return $a / $b;
	}
}

new APIcalculator();

It is important to extend the APIcalculator class with the \TPsoft\APIlite\APIlite class, which will provide the entire API servicing according to public methods along with JSON and HTML documentation. The HTML documentation is generated based on the documentation snippet for each method.

Outputs

When you run this subfile through the webserver, you will see the JSON documentation in the browser

{
  "name": "APIcalculator",
  "html_version": "http://localhost/APIlite/test/APIcalculator.php?format=html",
  "javascript_version": "http://localhost/APIlite/test/APIcalculator.php?format=javascript",
  "typescript_version": "http://localhost/APIlite/test/APIcalculator.php?format=typescript",
  "actions": [
    {
      "name": "add",
      "doc": "/**\r\n\t * Add two numbers.\r\n\t * Standard plus operation.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The sum of the two numbers.\r\n\t */",
      "description": "Add two numbers.\nStandard plus operation.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    },
    {
      "name": "subtract",
      "doc": "/**\r\n\t * Subtract two numbers.\r\n\t * Standard minus operation.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The difference of the two numbers.\r\n\t */",
      "description": "Subtract two numbers.\nStandard minus operation.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    },
    {
      "name": "multiply",
      "doc": "/**\r\n\t * Multiply two numbers.\r\n\t * Standard multiplication operation.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The product of the two numbers.\r\n\t */",
      "description": "Multiply two numbers.\nStandard multiplication operation.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    },
    {
      "name": "divide",
      "doc": "/**\r\n\t * Divide two numbers.\r\n\t * Standard division operation. Throws an exception if dividing by zero.\r\n\t *\r\n\t * @param float $a The first number.\r\n\t * @param float $b The second number.\r\n\t * @return float The quotient of the two numbers. Throws an exception if dividing by zero.\r\n\t * @throws \\Exception If dividing by zero.\r\n\t */",
      "description": "Divide two numbers.\nStandard division operation. Throws an exception if dividing by zero.",
      "params": [
        {
          "name": "a",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The first number."
        },
        {
          "name": "b",
          "type": "float",
          "optional": false,
          "default": null,
          "doc": "The second number."
        }
      ],
      "return": "float"
    }
  ]
}

and there is also an HTML version available

The HTML documentation page also includes a built-in interactive tester. Each endpoint can be expanded with Try it, filled directly in the browser, and executed against the current API endpoint. If needed, you can set a shared Bearer token at the top of the page. The token is stored in localStorage and is sent as Authorization: Bearer ... for test requests made from that page.

You can also download generated frontend clients:

• JavaScript: ?format=javascript
• TypeScript (typed for Vue/TS projects): ?format=typescript

Both generated clients support a shared Bearer token helper. Call bearerSet(token) once, the token is stored in localStorage under apilite_bearer_token, and subsequent requests automatically send Authorization: Bearer ....

Both generated clients also support response hooks:

• addResponseHandler(handler) registers a handler called for every API response.
• addErrorHandler(handler) registers a handler called only when the API response has status === 'ERROR'.
• Both methods return an unsubscribe function.
• Handlers receive (response, context), where context contains method, data, and httpStatus.
• Handler exceptions are ignored, so they do not change the original API callback or promise result.

JavaScript usage example:

import backend from './backend.js';

backend.bearerSet('your-access-token');
const removeErrorHandler = backend.addErrorHandler((response, context) => {
	console.error(context.method, response.msg);
});

backend.add(1, 2).then((response) => {
	console.log(response.data);
});

// removeErrorHandler();

TypeScript usage example (Vue + TS):

import backend from './backend';

backend.bearerSet('your-access-token');
const removeResponseHandler = backend.addResponseHandler((response, context) => {
	console.log(context.httpStatus, response.status);
});

backend.add(1, 2).then((response) => {
	console.log(response.data); // typed value based on PHP return type
});

// removeResponseHandler();

If a method return type is a PHP class with public properties, JSON help now also includes return_structure, and the generated TypeScript client maps that class to an object shape based on those public properties.

These outputs can also be generated in command line:

• HTML: $> php APIcalculator.php --html
• JavaScript: $> php APIcalculator.php --javascript > backend.js (--js alias is available)
• TypeScript: $> php APIcalculator.php --typescript > backend.ts

HTML help tester notes

The built-in HTML tester currently follows the default APIlite request model:

• request method is POST
• endpoint action is sent as query parameter action
• request fields are sent as top-level form fields
• object and array field values are serialized as JSON strings

Because the current metadata does not explicitly distinguish path params, query params and request body schemas, the HTML tester renders the parts that are reliably available today and keeps the rest minimal.