Tawazon skeleton app
=====================

# 1. Setup Tawazon Skeleton
 

## Makefile based setup

By default PHP8.1 is used. If you want to use older version, just export environment variable and different version will
be used. e.g.

```
export PHP_VERSION=8.1
```

To speed up things a bit, you can just enter this one/liner and set up the whole project:

```bash
git clone --branch main https://github.com/mouadhbenalaya/tawazon.git
```

---
**NOTE**

- Please keep in mind to replace the default `tawazon` directory name with your own.
- To store git credentials on disk, please use `git-credential-store` command (https://git-scm.com/docs/git-credential-store#_examples)


---

For more `make` commands type `make` to get help.

## Manual setup

Clone this repository on your development machine:

```bash
git clone --branch main https://github.com/mouadhbenalaya/tawazon.git tawazon
cd tawazon
```

---
**NOTE**

- Please keep in mind to replace the default `tawazon` directory name with your own.
 
---

Copy   `.env.dev` to `.env`, set custom variables and spin up the
containers:

```bash
$ cp .env.local .env 
```

Enter the `php` container and use the built-in helper for running common tasks:
 
## Database setup

To create the database run the migrations to create tables, foreign keys etc.
This will also create telescope table

```
$ php artisan migrate --seed
```

Read more about managing your .env.local on localhost, dev, staging and production server here:
https://symfony.com/doc/current/configuration.html#selecting-the-active-environment

## Authentication & Security

### 1. Header Authenticator

- used for authenticating via API
- a header with `Authorization: Bearer YOUR_TOKEN` is sent
- tokens are stored in localstorage on users computer and in the database on the app server
- supports `refreshToken`

## Command Line

There are several Laravel artisan commands developed to speed up the development. Almost all of them are written in a
developer friendly way - they will ask you for required parameters and suggest defaults. These are:

| Command                    | Description                    |
|----------------------------|--------------------------------|
| `app:email:send`           | Test sending of email          |

# 4. Entities

## User

Default user with classic email & password login. Nothing out of the ordinary. Components needed for user are:

- User entity - the Laravel model itself
- User Controller - handles all the CRUD logic for user together with encoding the password

# 5. API & Versioning

Our API setup supports classic `JSON` response (no json-ld for now), can be easily modified to support `XML` as well.
Versioning is on by default, and Laravel is architectured in a way that supports API versions. See below for details.

## CRUD API

Entity and repository should be created manually inside `app/Https/Api` directory. The following types of endpoints
should be manage inside the entity:

- Create single entity
- Retrieve single entity
- Update single entity
- Delete single entity
- List entities, with pagination, sorting and search

## Swagger

Each API endpoint needs to be well documented. See our User / Token / Tag / Author / Book / File / Gallery entities for
best practices
and examples. All Swagger documentation will be generated automatically for you. You can override the default according
to your needs inside the entity file under `#[ApiResource]`.
Follow REST API standards for naming, or our own Laravel examples.

Swagger also only supports v2 versions, so you can check our docs on the following links:

- http://localhost/docs - for v2 - only one endpoint was changed, as an example

```
$ php artisan l5-swagger:generate  
```

## How to version your API

-- Need to decide what to write :)

## Deprecating old versions

First, lets get the naming straight - `.env` file has three separate parameters:

`API_UNSUPPORTED_VERSIONS` - these are the versions we no longer support (i.e. 'v1,v2')  
`API_SUNSET_VERSIONS` - these are the versions that are becoming deprecated soon, but still work to maintain some
Backwards Compatibility  
`API_LAST_VERSION` - last working version, if you're using this one, you're awesome :-)


## Captain Hooks

This additional feature is to ensure, validate or prepare your commit messages, ensure code quality or run unit tests
before you commit or push changes to git.
You can modify the default configuration `captainhooks.json` and add some script that might be helpful to check your
codes or updates before you commit and push.
It will automatically disable captainhooks.


---
**Note** : If you want to push or commit without passing the test or script on captainhooks configuration, you can add
the following command on every commit or push.

```
$ --no-verify
```

**Example**

```
$ git commit -m"messages to commit updates" --no-verify
$ git push origin BRANCH --no-verify
```

---

# 7. Postman integration

Postman is an application used for API testing. It is an HTTP client that tests HTTP requests, utilizing a graphical
user interface, through which we obtain different types of responses that need to be subsequently validated.
Q Api Platform skeleton comes with support for Postman. Just import [collection](docs/qaps.postman_collection.json) file
and the [environment variables](docs/qaps.postman_environment.json) into Postman and that's it.

There is also implemented `make` command to export Swagger documentation to Postman collection.