# APIlite

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
<?php
require_once __DIR__ . '/APIlite/src/APIlite.php';
```

or use composer

```bash
composer require tpsoft/apilite
```

and add to your project

```php
<?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
<?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

```js
{
  "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

<img src="test/Example.APIcalculator.png" />

You can also download generated frontend clients:

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

JavaScript usage example:

```js
import backend from './backend.js';

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

TypeScript usage example (Vue + TS):

```ts
import backend from './backend';

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

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`