# HoshiAI Laravel (backend)

HoshiAI-be — the backend part of the HoshiAI project for the Web Programming course at VTŠ. The project is built with Laravel and includes API documentation via Swagger. Authentication is handled using standard tokens.

## Libraries

* [Laravel (Sanctum for api)](https://laravel.com/)
* [L5-Swagger](https://github.com/DarkaOnLine/L5-Swagger)
* [mobiledetect/mobiledetectlib](https://packagist.org/packages/mobiledetect/mobiledetectlib)
* [openai-php/client](https://github.com/openai-php/client)

## External API
* [ip-api.com](http://ip-api.com/)
* [openai.com](https://openai.com/)

## Installation

1. Install php and composer
2. Install all dependecies for this project
```
composer install
```
3. Copy `.env.example` and make `.env` file. Fill db, email and openai token
```
DB_CONNECTION=mysql
DB_HOST=
DB_PORT=
DB_DATABASE=
DB_USERNAME=
DB_PASSWORD=
...
MAIL_MAILER=
MAIL_SCHEME=
MAIL_HOST=
MAIL_PORT=
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=
MAIL_FROM_ADDRESS=
...
OPENAI_MODEL=gpt-4.1-mini
OPENAI_KEY=
```
4. Make migrations to your db
```
php artisan migrate
```
5. Start dev server 
```
php artisan serve
```
6. Build this project in `/public/` folder for deploy
```
....
```

*P.s. To access Swagger and view all API endpoints, go to `/swagger/`.*

## About Laravel

**Laravel** is a modern PHP framework designed for building web applications quickly and efficiently. It provides an elegant syntax, powerful tools for routing, authentication, and database management, and follows the MVC (Model-View-Controller) architecture to help developers write clean and maintainable code.

### Sanctum

In this project we use **Laravel Sanctum**, lightweight authentication system for APIs in Laravel. It allows applications to issue and manage API tokens for users, enabling secure communication between clients (like web apps, mobile apps, or external services) and the backend.

#### Examples
Group of routes wrapped with the auth:sanctum middleware. This means that only authenticated users with valid API tokens can access these endpoints:
```php
Route::middleware('auth:sanctum')->group(function () {
    Route::get('/auth/me', [ AuthController::class, 'me' ])->middleware('auth:sanctum');
    Route::post('categories', [CategoryController::class, 'store']);
    Route::put('categories/{category}', [CategoryController::class, 'update']);
    Route::delete('categories/{category}', [CategoryController::class, 'destroy']);
});
```

Below simple `me()` method that returns information about the currently authenticated user. It uses the $request->user() helper to retrieve the logged-in user
```php
public function me(Request $request)
{
    return response()->json([
        'user' => new UserResource($request->user())
    ]);
}
```


### Eloquent ORM

For interacting with the database, we use `Eloquent ORM` (Object-Relational Mapper), which provides a simple and expressive syntax for working with database tables using PHP classes called models. Each model represents a table, and each model instance represents a record in that table.
```php
public function index()
{
    $this->authorize('viewAny', Log::class);
    return LogResource::collection(Log::paginate(self::PAGINATED_COUNT));
}
```

### Base Laravel Structure for this project

* `app/` — the main application directory that contains most of your project’s logic.
    * `Http/` — contains controllers, middleware, and requests that handle incoming web and API requests.
        * `Controllers/` - holds all controller classes that manage the logic between models and views or API responses. Controllers receive requests, process data (often using models), and return responses.
        * `Resources/` - contains resource classes that transform models and data into structured JSON responses for APIs. 
    * `Mail/` — includes classes responsible for sending emails.
    * `Models/` — holds Eloquent models that represent and interact with database tables.
    * `Policies/` — defines authorization logic for various models and user actions.
* `routes/` — stores all route definitions for the application.
    * `api.php` — contains routes specifically for API endpoints.
* `database/` — includes everything related to the database layer.
    * `migrations/` — holds migration files used to create and modify database tables.