lucent-laravel/README.md

# Lucent for Laravel 

## Installation 

### Requirements

- PHP 8.2
- Laravel 10
- Postgres or Sqlite database
- ImageMagick

### Composer

Currently the repository is private. So you need to contact me hi@lexx.gr in order to give you access.

Add the following to your composer.json file

```json
{
  "repositories": [
    {
      "type": "vcs",
      "url": "ssh://git@code.radical-elements.com:2727/lucent/lucent-laravel.git"
    }
  ]
}
```
Also add this line inside your required dependencies:

```
  "lexx27/lucent": "@dev"
```

and finally append this line in post-autoload-dump:
```json
{
  "scripts": {
    "post-autoload-dump": [
      "@php artisan vendor:publish --tag=lucent --force"
    ]
  }
}
```

Run composer install or update


### Environment and options

Run the following command to generate the configuration file:

```bash
php artisan vendor:publish
```
Choose Lucent from the prompted options.

The following config will get copied and I will explain each option

```php
<?php

return [
    "env" => , // The lucent environment. Set it as production if you are not a contributor
    "schemas_path" =>, // Where your schemas are located
    "database" => , // the database connection pgsql or sqlite 
    "name" => ,// The name tha will be shown on the admin panel. Default is Lucent 
    "url" => ,// the lucent url. Default is the Same as the app url.  
    "previewTarget" => ,// the Url where the preview button on the admin will point. Leave blank to hide the button,
    "generateCommand" => ,// The artisan command that will run on the admin to generate the static content. Default is generate:static
    "imageFilters" => [], // Define the ImageFilters directory
    "canInvite" => ["admin"], // Optionally if you have permission groups. Who can invite
    "canBuild" => ["admin"], // Optionally if you have permission groups. Who can build the website
    "systemUserId" => "", // If you import data programmatically, assign the user id that will be the creator
];
```

### Database

The recommended database for small website is sqlite. But you can also use postresql
Make sure to delete the existing migration scripts in your database/migrations folder.

Then run:

```bash
php artisan migrate
```

### First user

To create your first user, head to your localhost:8000/lucent
Enter your details and create the first user.
The authentication system is passwordless. So you have to have a dummy mailserver to work locally

Besides the first user, all the following user should be invited. Registrations do not exist as a concept.


## Schemas

Schemas are JSON files that describe your data. You should choose a folder to store them.
You can think of a schema as a database table and its field as a column. Create one JSON file per schema.

Let' say for example that you want to create a blog post, the schema could be:

```json
{
    "label": "Posts",
    "name": "posts", 
    "isEntry": true,
    "type": "collection",
    "visible": [
        "_sys.updatedAt",
        "status"
    ],
    "fields": [
        {
            "label": "Title",
            "name": "title",
            "required": true,
            "ui": "text"
        },
        {
            "label": "Slug",
            "name": "slug",
            "ui": "slug",
            "source": "title"
        },
        {
            "label": "Image",
            "name": "image",
            "ui": "file",
            "collections": ["images"],
            "max": 1
        },
        {
            "label": "Content",
            "name": "content",
            "ui": "rich"
        }
    ]
}

```

You can find all the available options on the Schema reference and the Field Reference page respectively.

Every time you need to apply the new schemas you should run the following command for them to take effetct:

```bash
php artisan lucent:schemas
```

## Images and files

Images and files have the exact same features as ordinary schemas. The only difference is that each records points to one file.
Other than that you can add fields and treat them as any other record.
You can create as many files schemas as you like, in order to organize your media.
Each schema maps to one directory.

If you try to upload the same file in the same schema, then the system will ignore it and return back the existing file as a response.

### Thumbnails
    
Lucent is a mix of a CMS and a static site generator. So image thumbnails are designed with that in mind.

For each thumbnail preset, you have to create a new PHP Class like so:

```php
<?php namespace App\Lucent\ImageFilters;
use Intervention\Image\Filters\FilterInterface;
use Intervention\Image\Image;

class Banner implements FilterInterface
{
    public function applyFilter(Image $image): Image
    {
        $image->fit(225, 225);
        return $image;
    }
}
```

Then you have to define this filter inside your lucent.php config file:

```php
return [
    "imageFilters" => [
        "banner" => \App\Lucent\ImageFilters\Banner::class,
    ], 
];
```
You can now use this filter inside your code:

```php
$image->file(FileObject,"banner"); // will generate and return the path to the thumbnail
```

If you want to obtain the path to the original file

```php
$image->path(FileObject);
```

Checkout the docs folder for more information