Getting started
Terminology, general concept
In Sharp, we handle entities
; and entity
is simply a data structure which has a meaning in the applicative context. For instance, a Person
, a Post
or an Order
. In the Eloquent world, for which Sharp is optimized, it's typically a Model — but it's not necessarily a 1-1 relationship, a Sharp entity
can represent a portion of a Model, or several Models.
Each instance of an entity
is called... an instance
.
Each entity
in Sharp can be displayed:
- in an
Entity List
, which is the list of all theinstances
for thisentity
: with some configuration and code, the user can sort the data, add filters, and perform a search. From there we also gain access to applicativecommands
applied to aninstance
or the whole list, and to a simplestate
changer (the publish state of an Article, for instance). All of that is described below. - In a
Show
, optionally, to display aninstance
details. - And in a
Form
, either to update or create a newinstance
.
Installation
Sharp 6 needs Laravel 7+ and PHP 7.4+.
- Add the package with composer:
composer require code16/sharp
- And then publish assets:
php artisan vendor:publish --provider="Code16\Sharp\SharpServiceProvider" --tag=assets
A tip on this last command: you'll need fresh assets each time Sharp is updated, so a good practice is to add the command in the scripts.post-autoload-dump
section of your composer.json
file:
"scripts": {
[...]
"post-autoload-dump": [
"Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
"@php artisan vendor:publish --provider=Code16\\Sharp\\SharpServiceProvider --tag=assets --force",
"@php artisan package:discover"
]
},
Configuration
Sharp needs a config/sharp.php
config file, mainly to declare entities
.
You can init this file with: php artisan vendor:publish --provider="Code16\Sharp\SharpServiceProvider" --tag=config
Here's an example:
return [
"entities" => [
"spaceship" => [
"list" => \App\Sharp\SpaceshipSharpList::class,
"form" => \App\Sharp\SpaceshipSharpForm::class,
"show" => \App\Sharp\SpaceshipSharpShow::class,
"validator" => \App\Sharp\SpaceshipSharpValidator::class,
"policy" => \App\Sharp\Policies\SpaceshipPolicy::class
]
]
];
As we can see, each entity
(like spaceship
, here), can define:
- a
list
class, responsible for theEntity List
, - a
show
class, responsible for displaying aninstance
, - a
form
class, responsible for... theForm
- a
validator
class, to handle form validation - and a
policy
class, for authorization.
Almost each one is optional, in fact: we could skip the show
and go straight to the form
from the list
, for instance.
We'll get into all those classes in this document. The important thing to notice is that Sharp provides base classes to handle all the wiring (and more), but as we'll see, the applicative code is totally up to you.
Access to Sharp
Once installed, Sharp is accessible via the url /sharp
, by default. If you wish to change this default value, you'll need to define the custom_url_segment
config value, in config/sharp.php
:
return [
"name" => "Saturn",
"custom_url_segment" => "admin",
[...]
]