diff --git a/docs/configuration.md b/docs/configuration.md index 5923994..76e9d2b 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -15,10 +15,11 @@ For non-core options (for example UI options), take a look at [Settings](https:/ | `TIMEZONE` | The timezone of your photos., requires a named timezone identifier like `Europe/Paris` | system timezone of server | | `LYCHEE_UPLOADS` | Path to uploads directory | `uploads/` inside `public/` | | `LYCHEE_UPLOADS_URL` | URL to uploads directory, better left empty | `/uploads` | +| `APP_FORCE_HTTPS` | Force HTTPS on all URLs | `false` | | `TRUSTED_PROXIES` | Trusted proxy IP addresses | `null` | | `LOG_VIEWER_ENABLED` | Enable log viewer inside Lychee instead of through CLI. | `true` | -| `LIVEWIRE_ENABLED` | Enable v5 Livewire frontend; set to `false` if the new frontend doesn't work on our installation (this is a **temporary** workaround). | `true` | - +| `VUEJS_ENABLED` | Enable v6 VueJs frontend; set to `false` if the new frontend doesn't work on our installation (this is a **temporary** workaround). | `true` | +| `LEGACY_API_ENABLED` | Enable the Legacy API. It will also be enabled if `VUEJS_ENABLED` is set to `false`. | `false` | > {note} `APP_URL` must only contain the hostname up to the Top Level Domain (tld) _e.g._ .com, .org etc. > If you are using Lychee in a sub folder, specify the path after the tld here in the `APP_DIR` constant. diff --git a/docs/livewire.md b/docs/livewire.md deleted file mode 100644 index 1e85139..0000000 --- a/docs/livewire.md +++ /dev/null @@ -1,159 +0,0 @@ -## A brief introduction to Livewire - -We first give a short intuition of how [Livewire](https://livewire.laravel.com/docs/quickstart), the framework of the new front-end, works. - -### Livewire and Controllers - -The Laravel framework on which Lychee is based provides two options regarding how a request may be routed: - -- the request is directed to a controller below `app/Http/Controllers` -- the request is directed to a Livewire component below `app/Livewire/Components` - -In the first case, a controller returns a JSON object or an HTML page rendered from a blade template. -In the second case (Livewire), only a block of HTML built from a blade template will be returned. - -From a very high level, Livewire makes use of two folders: - -- `app/Livewire/Components` which hosts the components and their inner logic. -- `resources/views/{components|livewire}` which hosts the HTML layout of the components. - -So far one could say there is not much difference with a normal request life cycle. Where Livewire starts to shine is in the ability to call the methods of the component directly _from HTML_. Instead of having to use a JavaScript hook, make an AJAX call, parse the result, and update the layout accordingly, the user/programmer can directly interact with the designated component and Livewire takes care of the request and rendering. - -### Laravel Components - -In Laravel, it is possible to create reusable templates also called components. They are called from the blade part using the following syntax: -```html - -``` -Note that PHP expressions and variables should be passed to the component via attributes that use the `:` character as a prefix (in this case `data`). -Attributes are automatically inserted in the constructor of the component: -```php -public function __construct(AbstractAlbum $data) -{ - // component logic for the rendering -} -``` -Laravel then calls the `render()` method and returns the corresponding view. -```php -public function render() -{ - return view('components.gallery.album'); -} - -``` -Public attributes in the component class (e.g. `public string $title`) are then accessible in the blade template part: -```html - -
-

{{ $title }}

-
- -``` - -### Livewire Components - -Similarly to Laravel components, the Livewire ones use the `render()` method, blade views, and public attributes. -One could say that the Livewire components are just Laravel components on steroids. - -In order to call Livewire, the following syntax is used: -```html - -``` -This will call the Livewire component located at `app/Livewire/Components/Pages/Gallery/Album.php`. -As opposed to their Laravel counterparts, it is not possible to use the constructor to read the attributes. -For this reason a method `mount()` has been added: -```php -public function mount(AbstractAlbum $album) -{ - $this->load($album); -} -``` -Then the `render()` function is used in order to retrieve the respective HTML section of the component. -```php -public function render() -{ - return view('livewire.pages.gallery.album'); -} -``` - -#### Calling methods - -Where Livewire becomes interesting is in its ability to call PHP functions directly from user-land. -Methods of the component can be callable by using additional HTML attributes. -For example in `resources/views/livewire/pages/gallery/albums.php` the attribute `wire:click="login"` -will call the `login()` method of the component `app/Livewire/Pages/Gallery/Album.php` -```html - - - -``` -```php -public function login() -{ - // ... -} -``` -This method will then execute and trigger a re-rendering of the component. - -#### Emitting events - -In addition to calling a method of a component, -it is also possible to trigger actions in other components. -As a matter of fact, in the specific case of the `login()` method, -we are emitting an event which will trigger the opening of the `app/Livewire/Components/Base/Modal.php` component with a login form: -```php -protected function login() -{ - $form = 'forms.login'; - $params = []; - $this->dispatch('openModal', $form, $params)->to(Modal::class); -} -``` -`Modal.php` contains the following code: -```php -class Modal extends Openable -{ - #[On('openModal')] - public function openModal(string $type, array $params = []) - { - //... - } -``` -The attribute `#[On('event-name')]` informs the component which events it needs to react to. -In this specific case `openModal()` method has two arguments which are provided by the `$this->dispatch('eventName', $arg1, $arg2);` - -With these tools at hand, we are now able to understand a bit better the structure of the Livewire front-end. - -## Lychee Livewire Front-end - -Since Livewire v3, the front-end uses a layout which is significantly close to a normal website. -We make use of `navigate`. Read more [here](https://livewire.laravel.com/docs/navigate) - -Each page is now located in `App/Livewire/Components/Page` with the exception of the different gallery views which are in -`App/Livewire/Components/Page/Gallery`. - -This makes use of a unified layout provided in `resources/views/components/layouts/app.blade.php`. - -**More info to come.** - -## Pitfalls & Wireable - -There are a few points where special attention is required. At the end of lifecycle of a request, -Livewire deserializes the components and forwards them to the client in an encrypted and hashed form. -When executing a method call from user-land, component's data are sent to the server and deserialized. -If an attribute of the component is an `Interface`, Livewire will panic. It uses the type of the attribute -to retrieve the constructor and hydrate the model. - -Do note that by default, the dehydration uses the `toArray()` method. As a result the hydration will not be working in most cases. -For this reason Livewire proposes the interface `Wireable` which requires two methods: `toLivewire()` and `static fromLivewire($value)`. -The former will return the serialized version of the object and the latter will rebuild the object from the serialized version. - -Another option is to use Synthesizers. Examples which take care of AbstractAlbums and Photos are in `App/Livewire/Synth`; - -## Front-end reactivity - -While Livewire provides decent interaction, sometimes we do not need round trips to the server to change the displayed data. -For this reason we use [Alpine.js](https://alpinejs.dev/start-here) which is bundled with Livewire. - -Alpine provides convenient tools to improve reactivity such as `x-on`, `x-bind`, `x-data`, `x-show`, `x-init`, `x-cloak`. -We advise the reader to familiarize themselves with those as they are also used in the frontend. diff --git a/docs/org.md b/docs/org.md deleted file mode 100644 index 862d762..0000000 --- a/docs/org.md +++ /dev/null @@ -1,36 +0,0 @@ -## Introduction - -Lychee was originally developed by [electerious][1] ([Tobias Reich][2]). Lychee aims to be a great looking and easy-to-use photo-management-system that nearly anyone can use on their web server. - -Since April 1st, 2018 this project has moved to its own Organisation (LycheeOrg) where people are able to submit their fixes to it. We, the Organisation owners, want to thank electerious (Tobias Reich) for the opportunity to make this project live on. - -## Schedule releases & Roadmap - -We do not have schedule for releases such as every 6 months. Our releases should never contain breaking changes. That being said, we do not provide backward compatibility or hotfix for older versions. The `master` branch is the bleeding edge of Lychee. It contains the latest bugfixes and newest features. Once a sufficient number of hotfixes or new features has been merged into `master` we create a new release. - -Generally, we follow semantic versioning: Major.minor.patch. - -- Major releases provide a breaking change or significant refactoring of the full project (_e.g._, migration to a new front-end). -- minor releases have a database structural update or provide a notable change. -- patches for the rest. - -## Security - -In order to ensure maximum security some actions on Lychee are restricted by an admin authentication. The username and password are stored hashed with bcrypt in the database. - -However as precaution, we provide a server-side command to easily erase those two data from the database in order to recover admin access. We consider this command safe as it requires a command line access to the server. A user gaining such rights is outside of our security scope as the server would be compromised. - -## LycheeOrg - -LycheeOrg is a GitHub organization of enthusiast developers determined to keep this project alive. -There is no commitment in time to the project. We understand that each member has their personal life and dedicate time as they see fit to the project. - -If you start to contribute by opening multiple Pull Requests and adding more code to the database, it is likely you will be asked to join us. - -There is no governance model. We currently have three admins: [d4715][3], [ildyria][4], [LudovicRousseau][5]. Decisions are made after discussions. - -[1]: https://github.com/electerious -[2]: https://electerious.com -[3]: https://github.com/d7415 -[4]: https://github.com/ildyria -[5]: https://github.com/LudovicRousseau diff --git a/docs/structure.md b/docs/structure.md index 82fb424..d58d5af 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -31,7 +31,13 @@ The `resources` directory contains your views as well as the TypeScript and CSS ### The Routes Directory The `routes` directory contains all of the route definitions for Lychee. Several route files are included with Lychee: -`api.php`, `web-admin.php`, `web-install.php`, `web-livewire.php`, and `web.php`. +`api-v1.php`, `api-v2.php`, `web-admin-v1.php`, `web-admin-v2.php`, `web-install.php`, `web-v1.php`, and `web-v2.php`. + +This makes the separation between the two REST API: +- `v1` routes are used by legacy endpoints, i.e. version 4 of Lychee. This is mostly used as POST requests. +- `v2` routes are used by the Version 6 front-end with VueJs. It makes use of a more proper REST definition with PATCH, POST, GET and DELETE. + +By default `v1` routes are disabled since version 6. ### The Storage Directory The `storage` directory contains your compiled Blade templates, file based sessions, file caches, and other files generated by the framework. This directory is segregated into `app`, `framework`, and `logs` directories. The `app` directory may be used to store any files generated by your application. The `framework` directory is used to store framework generated files and caches. Finally, the `logs` directory contains Laravel's log files (useful in case of hard crash). @@ -53,7 +59,7 @@ The `vendor` directory contains your [Composer][2] dependencies. ## The App Directory The majority of Lychee is housed in the `app` directory. By default, this directory is namespaced under `App` and is autoloaded by Composer using the [PSR-4 autoloading standard][3]. -The `app` directory contains a variety of additional directories such as `Console`, `Http`, `Livewire` and `Providers`. Think of the `Console`, `Livewire`, and `Http` directories as providing an API into the core of your application. The HTTP protocol and CLI are both mechanisms to interact with Lychee, but do not actually contain application logic. In other words, they are two ways of issuing commands to Lychee. The `Console` directory contains all of the Artisan commands, while the `Http` directory contains your controllers, middleware, and requests. Furthermore the `Livewire` directory contains the serverside code necessary for the new front-end. +The `app` directory contains a variety of additional directories such as `Console`, `Http`, and `Providers`. Think of the `Console` and `Http` directories as providing an API into the core of your application. The HTTP protocol and CLI are both mechanisms to interact with Lychee, but do not actually contain application logic. In other words, they are two ways of issuing commands to Lychee. The `Console` directory contains all of the Artisan commands, while the `Http` directory contains your controllers, middleware, and requests. ### The Console Directory The `Console` directory contains all of the custom Artisan commands for Lychee. These commands may be generated using the `make:command` command. @@ -81,9 +87,6 @@ The `Image` directory contains our image handler. We provide here two ways to ma - with GD, - with imagick. -### The Livewire Directory -The `Livewire` directory contains the server-side logic for the Livewire front-end. See more [here](livewire.html) - ### The Metadata Directory The `Metatdata` directory contains logic related to data such as Exif information, geodecoding, lychee version, GitHub monitoring... diff --git a/gen.py b/gen.py index 9c7e415..fdc9aeb 100644 --- a/gen.py +++ b/gen.py @@ -42,7 +42,6 @@ def generate_base(): pages_title = {} -pages_title['org'] = 'Lychee & LycheeOrg' pages_title['releases'] = 'Release Notes' pages_title['installation'] = 'Installation' @@ -66,10 +65,9 @@ def generate_base(): pages_title['architecture'] = 'Lychee logic overview' pages_title['structure'] = 'Directory Structure' pages_title['frontend'] = 'Front-end' -pages_title['livewire'] = 'Livewire Front-end (alpha)' structure = [['Prologue', - ['org', 'releases']]] + ['releases']]] structure += [['Getting Started', ['installation', 'configuration', 'docker', 'update', 'upgrade']]] structure += [['Advanced Topics', @@ -77,7 +75,7 @@ def generate_base(): structure += [['Frequently Asked Question', ['faq_general', 'faq_installation', 'faq_troubleshooting']]] structure += [['Contributing', - ['contributions', 'api', 'architecture', 'structure', 'frontend', 'livewire']]] + ['contributions', 'api', 'architecture', 'structure', 'frontend']]] def gen_github_link(page):