From 8e8eef22297d542ec35e173838cc70e5e7ec69e0 Mon Sep 17 00:00:00 2001 From: seralexs Date: Sun, 19 Jun 2022 00:08:21 +0300 Subject: [PATCH] doc blocks for resources --- src/Contracts/Resources/ResourceContract.php | 73 +++++++++++++++++++- src/MoonShine.php | 13 ++++ src/Resources/Resource.php | 59 ++++++++++++++-- src/Traits/Fields/FormElementTrait.php | 8 +++ 4 files changed, 145 insertions(+), 8 deletions(-) diff --git a/src/Contracts/Resources/ResourceContract.php b/src/Contracts/Resources/ResourceContract.php index b270a6e4a..c279e34f1 100644 --- a/src/Contracts/Resources/ResourceContract.php +++ b/src/Contracts/Resources/ResourceContract.php @@ -4,36 +4,107 @@ use Illuminate\Database\Eloquent\Model; use Illuminate\Support\Collection; +use Leeto\MoonShine\Actions\Action; use Leeto\MoonShine\Contracts\RenderableContract; +use Leeto\MoonShine\Decorations\Tab; +use Leeto\MoonShine\Fields\Field; interface ResourceContract { + /** + * Get a resource title, will be displayed in admin panel menu + * + * @return string + */ public function title(): string; + /** + * Define a field name, which will be used to display value in relation + * + * @return string + */ public function titleField(): string; + /** + * Get a model class, related to resource + * + * @return Model + */ public function getModel(): Model; + /** + * Get current eloquent instance + * + * @return Model + */ public function getItem(): Model; + /** + * Get a collection of additional actions performed on resource page + * + * @return Action[] + */ public function getActions(): Collection; + /** + * Define if the resources protected by authentication + * + * @return bool + */ public function isWithPolicy(): bool; + /** + * Get a collection of fields of related model + * + * @return Field[] + */ public function getFields(): Collection; + /** + * Get a collection of tabs, which will be displayed on create/update resource form + * + * @return Tab[] + */ public function tabs(): Collection; + /** + * Get a collection of fields of related model, which will be displayed on resource index page + * + * @return Field[] + */ public function indexFields(): Collection; + /** + * Get a collection of fields of related model, which will be exported + * + * @return Field[] + */ public function exportFields(): Collection; + /** + * Get an array of fields, which will be displayed on create/edit resource page + * + * @return Field[] + */ public function formFields(): Collection; + /** + * Get additional assets, which will be loaded on resource page + * + * @param string $type CSS or JS type + * @return array + */ public function getAssets(string $type): array; public function extensions($name, Model $item): string; + /** + * Check whether user can perform action on model + * + * @param string $ability view, viewAny, restore, forceDelete + * @param Model|null $item Model on which the action is performed + * @return bool + */ public function can(string $ability, Model $item = null): bool; public function renderDecoration(RenderableContract $decoration, Model $item); @@ -42,5 +113,5 @@ public function renderField(RenderableContract $field, Model $item); public function renderFilter(RenderableContract $field, Model $item); - public function renderMetric(RenderableContract $field); + public function renderMetric(RenderableContract $metric); } \ No newline at end of file diff --git a/src/MoonShine.php b/src/MoonShine.php index 6a0bd0646..c521f3c18 100644 --- a/src/MoonShine.php +++ b/src/MoonShine.php @@ -33,6 +33,12 @@ public static function namespace(string $path = ''): string return static::NAMESPACE . $path; } + /** + * Register resource classes in the system + * + * @param array $data Array of resource classes that is registering + * @return void + */ public function registerResources(array $data): void { $this->resources = collect(); @@ -66,6 +72,8 @@ public function registerResources(array $data): void } /** + * Get collection of registered resources + * * @return Resource[] */ public function getResources(): Collection @@ -73,6 +81,11 @@ public function getResources(): Collection return $this->resources; } + /** + * Register moonshine routes and resources routes in the system + * + * @return void + */ protected function addRoutes(): void { Route::prefix(config('moonshine.route.prefix')) diff --git a/src/Resources/Resource.php b/src/Resources/Resource.php index f31b2a514..d39ca7802 100644 --- a/src/Resources/Resource.php +++ b/src/Resources/Resource.php @@ -7,6 +7,7 @@ use Illuminate\Contracts\View\Factory; use Illuminate\Contracts\View\View; use Illuminate\Database\Eloquent\Builder; +use Illuminate\Database\Eloquent\Scope; use Illuminate\Support\Collection; use Illuminate\Database\Eloquent\Model; use Illuminate\Support\Facades\Gate; @@ -25,6 +26,7 @@ use Leeto\MoonShine\Fields\Field; use Leeto\MoonShine\Filters\Filter; +use Leeto\MoonShine\Metrics\Metric; use Leeto\MoonShine\MoonShine; abstract class Resource implements ResourceContract @@ -55,30 +57,61 @@ abstract class Resource implements ResourceContract protected Model $item; + /** + * Get an array of validation rules for resource related model + * + * @see https://laravel.com/docs/validation#available-validation-rules + * + * @param Model $item + * @return array + */ abstract function rules(Model $item): array; /** + * Get an array of visible fields on resource page + * * @return Field[] */ abstract function fields(): array; /** + * Get an array of filters displayed on resource index page + * * @return Filter[] */ abstract function filters(): array; /** + * Get an array of additional actions performed on resource page + * * @return Action[] */ abstract function actions(): array; + /** + * Get an array of fields which will be used for search on resource index page + * + * @return array + */ abstract function search(): array; + /** + * Get an array of filter scopes, which will be applied on resource index page + * + * @see https://laravel.com/docs/eloquent#writing-global-scopes + * + * @return Scope[] + */ public function scopes(): array { return []; } + /** + * Get an array of metrics which will be displayed on resource index page + * + * @return Metric[] + */ public function metrics(): array { return []; @@ -220,21 +253,25 @@ public function getFields(): Collection } /** - * @return BaseFilter\[] + * @return Filter[] */ public function getFilters(): Collection { return collect($this->filters()); } - /* @return Tab[] */ + /** + * @return Tab[] + */ public function tabs(): Collection { return collect($this->fields()) ->filter(fn ($item) => $item instanceof Tab); } - /* @return Field[] */ + /** + * @return Field[] + */ public function whenFields(): Collection { return collect($this->getFields()) @@ -257,14 +294,18 @@ public function isWhenConditionField(string $name): bool return $this->whenFieldNames()->has($name); } - /* @return Field[] */ + /** + * @return Field[] + */ public function indexFields(): Collection { return $this->getFields() ->filter(fn (RenderableContract $field) => $field instanceof Field && $field->showOnIndex); } - /* @return Field[] */ + /** + * @return Field[] + */ public function formFields(): Collection { $fields = $this->extensionsFields(); @@ -273,7 +314,9 @@ public function formFields(): Collection ->filter(fn (RenderableContract $field) => $field instanceof Field && $field->showOnForm)); } - /* @return Field[] */ + /** + * @return Field[] + */ public function extensionsFields(): Collection { $fields = collect(); @@ -288,7 +331,9 @@ public function extensionsFields(): Collection return $fields; } - /* @return Field[] */ + /** + * @return Field[] + */ public function exportFields(): Collection { return $this->getFields() diff --git a/src/Traits/Fields/FormElementTrait.php b/src/Traits/Fields/FormElementTrait.php index 9695f5315..8a4ad9c54 100644 --- a/src/Traits/Fields/FormElementTrait.php +++ b/src/Traits/Fields/FormElementTrait.php @@ -28,6 +28,14 @@ trait FormElementTrait protected static string $view = ''; + /** + * Creates a form element class: Field,Filter + * + * @param ...$arguments $label Form element label, will be displayed in moonshine admin panel, + * $field Field name from database, which will be used for this form element + * $resource Instance of related resource class, if form element is a relation + * @return static + */ public static function make(...$arguments): static { return new static(...$arguments);