From 938190fa8d4460bd3c28906dbe729770968de519 Mon Sep 17 00:00:00 2001 From: jdw5 Date: Fri, 26 Apr 2024 09:28:21 +1000 Subject: [PATCH] Function documentation --- src/Concerns/HasActions.php | 31 ++++++++++++++++++- src/Concerns/HasLabel.php | 14 +++++++-- src/Concerns/HasMetadata.php | 21 +++++++++++++ src/Concerns/HasName.php | 17 ++++++++++ src/Concerns/HasRefinements.php | 25 ++++++++++++++- src/Table/Actions/Actions.php | 14 +++++++-- src/Table/Actions/BaseAction.php | 17 +++++++--- src/Table/Actions/Concerns/HasMethod.php | 2 +- .../Exceptions/InvalidEndpointMethod.php | 2 +- src/Table/Columns/Concerns/HasFallback.php | 31 ++++++++++++------- src/Table/Columns/Concerns/IsPreferable.php | 2 +- .../Columns/Exceptions/KeyCannotBeDynamic.php | 2 +- 12 files changed, 150 insertions(+), 28 deletions(-) diff --git a/src/Concerns/HasActions.php b/src/Concerns/HasActions.php index 99d59a8..9866d1d 100644 --- a/src/Concerns/HasActions.php +++ b/src/Concerns/HasActions.php @@ -8,12 +8,15 @@ use Jdw5\Vanguard\Table\Actions\InlineAction; use Illuminate\Support\Collection; +/** + * Define a class as having actions. + */ trait HasActions { protected mixed $actions = null; /** - * Define the actions for the table. + * Define the actions for the class. * * @return array */ @@ -22,27 +25,53 @@ protected function defineActions(): array return []; } + /** + * Retrieve the actions for the class. + * + * @return Collection + */ public function getActions(): Collection { return $this->actions ??= collect($this->defineActions()) ->filter(static fn (BaseAction $action): bool => !$action->isExcluded()); } + /** + * Retrieve the inline actions for the class. + * + * @return Collection + */ public function getInlineActions(): Collection { return $this->getActions()->filter(static fn (BaseAction $action): bool => $action instanceof InlineAction)->values(); } + /** + * Retrieve the bulk actions for the class. + * + * @return Collection + */ public function getBulkActions(): Collection { return $this->getActions()->filter(static fn (BaseAction $action): bool => $action instanceof BulkAction)->values(); } + /** + * Retrieve the page actions for the class. + * + * @return Collection + */ public function getPageActions(): Collection { return $this->getActions()->filter(static fn (BaseAction $action): bool => $action instanceof PageAction)->values(); } + /** + * Retrieve the default action for the class. + * + * @return BaseAction if a default is defined + * @return null if no default is defined + */ public function getDefaultAction(): ?BaseAction { return $this->getActions()->first(static fn (BaseAction $action): bool => $action instanceof InlineAction && $action->isDefault()); diff --git a/src/Concerns/HasLabel.php b/src/Concerns/HasLabel.php index 9a33b6e..2f29be9 100644 --- a/src/Concerns/HasLabel.php +++ b/src/Concerns/HasLabel.php @@ -2,12 +2,15 @@ namespace Jdw5\Vanguard\Concerns; +/** + * Set a label for a class. + */ trait HasLabel { protected mixed $label; /** - * Chainable method for setting the label. + * Set the label, chainable. * * @param mixed $label * @return static @@ -19,12 +22,12 @@ public function label(mixed $label): static } /** - * Set the label. + * Set the label quietly. * * @param mixed $label * @return void */ - public function setLabel(mixed $label): void + protected function setLabel(mixed $label): void { $this->label = $label; } @@ -38,4 +41,9 @@ public function getLabel(): mixed { return $this->evaluate($this->label); } + + protected function labelise(string $name): string + { + return str($name)->headline()->lower()->ucfirst(); + } } diff --git a/src/Concerns/HasMetadata.php b/src/Concerns/HasMetadata.php index af550f1..6ab0dbe 100644 --- a/src/Concerns/HasMetadata.php +++ b/src/Concerns/HasMetadata.php @@ -2,21 +2,42 @@ namespace Jdw5\Vanguard\Concerns; +/** + * Set metadata properties on a class + */ trait HasMetadata { + /** Metadata are non-uniform properties for the class */ protected array|\Closure $metadata = []; + /** + * Set the metadata, chainable. + * + * @param array|\Closure $metadata + * @return static + */ public function metadata(array|\Closure $metadata): static { $this->setMetadata($metadata); return $this; } + /** + * Set the metadata quietly. + * + * @param array|\Closure $metadata + * @return void + */ protected function setMetadata(array|\Closure $metadata): void { $this->metadata = $metadata; } + /** + * Get the metadata. + * + * @return array + */ public function getMetadata(): array { return $this->evaluate($this->metadata); diff --git a/src/Concerns/HasName.php b/src/Concerns/HasName.php index 78c63ae..ea90172 100644 --- a/src/Concerns/HasName.php +++ b/src/Concerns/HasName.php @@ -6,17 +6,34 @@ trait HasName { protected string|\Closure $name; + /** + * Set the name, chainable. + * + * @param string|\Closure $name + * @return static + */ public function name(string|\Closure $name): static { $this->setName($name); return $this; } + /** + * Set the name quietly. + * + * @param string|\Closure $name + * @return void + */ protected function setName(string|\Closure $name): void { $this->name = $name; } + /** + * Get the name + * + * @return string + */ public function getName(): string { return $this->evaluate($this->name); diff --git a/src/Concerns/HasRefinements.php b/src/Concerns/HasRefinements.php index 1ed84d3..1f78250 100644 --- a/src/Concerns/HasRefinements.php +++ b/src/Concerns/HasRefinements.php @@ -7,21 +7,40 @@ use Jdw5\Vanguard\Refining\Sorts\BaseSort; use Jdw5\Vanguard\Refining\Filters\BaseFilter; +/** + * Define a class as having a list of refinement options. + */ trait HasRefinements { + /** Caching the refinements */ private mixed $refinements = null; + /** + * Define the refinements for the class. + * + * @return array + */ protected function defineRefinements(): array { return []; } + /** + * Retrieve the refinements for the class. + * + * @return Collection + */ protected function getRefinements(): Collection { return $this->refinements ??= collect($this->defineRefinements()) ->filter(static fn (Refinement $refinement): bool => !$refinement->isExcluded()); } + /** + * Retrieve an associative array of filters keyed to their name. + * + * @return array + */ protected function getFilters(): array { return $this->getRefinements()->mapWithKeys(function (Refinement $refinement) { @@ -32,7 +51,11 @@ protected function getFilters(): array })->toArray(); } - + /** + * Retrieve an associative array of sorts keyed to their name. + * + * @return array + */ protected function getSorts(): array { return $this->getRefinements()->mapWithKeys(function (Refinement $refinement) { diff --git a/src/Table/Actions/Actions.php b/src/Table/Actions/Actions.php index 23139af..9a5cee0 100644 --- a/src/Table/Actions/Actions.php +++ b/src/Table/Actions/Actions.php @@ -46,11 +46,11 @@ public function defineActions(): array } /** - * Serialize the actions. + * Retrieve the actions as an array. * * @return array */ - public function jsonSerialize(): array + public function toArray(): array { return [ 'inline' => $this->getInlineActions(), @@ -59,4 +59,14 @@ public function jsonSerialize(): array 'default' => $this->getDefaultAction(), ]; } + + /** + * Serialize the actions. + * + * @return array + */ + public function jsonSerialize(): array + { + return $this->toArray(); + } } \ No newline at end of file diff --git a/src/Table/Actions/BaseAction.php b/src/Table/Actions/BaseAction.php index 10e6179..ed3da63 100644 --- a/src/Table/Actions/BaseAction.php +++ b/src/Table/Actions/BaseAction.php @@ -7,8 +7,6 @@ use Jdw5\Vanguard\Concerns\HasLabel; use Jdw5\Vanguard\Concerns\IsIncludable; use Jdw5\Vanguard\Concerns\HasMetadata; -use Jdw5\Vanguard\Concerns\SetsLabel; -use Jdw5\Vanguard\Table\Actions\Concerns\DependsOn; use Jdw5\Vanguard\Table\Actions\Concerns\HasEndpoint; abstract class BaseAction extends Primitive @@ -18,12 +16,11 @@ abstract class BaseAction extends Primitive use HasName; use IsIncludable; use HasEndpoint; - use SetsLabel; final public function __construct(string $name) { - $this->name($name); - $this->label($this->nameToLabel($name)); + $this->setName($name); + $this->setLabel($this->labelise($name)); $this->setUp(); } @@ -32,6 +29,11 @@ public static function make(string $name): static return resolve(static::class, compact('name')); } + /** + * Retrieve the action as an array. + * + * @return array + */ public function toArray(): array { return [ @@ -41,6 +43,11 @@ public function toArray(): array ]; } + /** + * Serialize the action to JSON. + * + * @return array + */ public function jsonSerialize(): array { return $this->toArray(); diff --git a/src/Table/Actions/Concerns/HasMethod.php b/src/Table/Actions/Concerns/HasMethod.php index 67a0f03..f566f9d 100644 --- a/src/Table/Actions/Concerns/HasMethod.php +++ b/src/Table/Actions/Concerns/HasMethod.php @@ -47,7 +47,7 @@ public function getMethod(): string protected function setMethod(string|\Closure $method): void { if (\is_string($method) && ! \in_array($method, ['get', 'post', 'put', 'patch', 'delete'])) { - throw InvalidEndpointMethod::with($method); + throw InvalidEndpointMethod::make($method); } $this->method = $method; } diff --git a/src/Table/Actions/Exceptions/InvalidEndpointMethod.php b/src/Table/Actions/Exceptions/InvalidEndpointMethod.php index 91a97bb..42bcc2a 100644 --- a/src/Table/Actions/Exceptions/InvalidEndpointMethod.php +++ b/src/Table/Actions/Exceptions/InvalidEndpointMethod.php @@ -4,7 +4,7 @@ class InvalidEndpointMethod extends \Exception { - public static function with(string $method): self + public static function make(string $method): self { return new static("The method {$method} is not a valid endpoint method"); } diff --git a/src/Table/Columns/Concerns/HasFallback.php b/src/Table/Columns/Concerns/HasFallback.php index 1ea0820..41208d8 100644 --- a/src/Table/Columns/Concerns/HasFallback.php +++ b/src/Table/Columns/Concerns/HasFallback.php @@ -3,18 +3,14 @@ namespace Jdw5\Vanguard\Table\Columns\Concerns; /** - * Trait HasFallback - * - * Set a fallback/backup property for a column - * - * @property mixed $fallback + * Set a fallback/backup property for a class. */ trait HasFallback { - protected mixed $fallback = null; + protected mixed $fallback; /** - * Set the fallback value for the column + * Set the fallback value, chainable. * * @param mixed $fallback * @return static @@ -22,27 +18,38 @@ trait HasFallback */ public function fallback(mixed $fallback): static { - $this->fallback = $fallback; + $this->setFallback($fallback); return $this; } /** - * Check if the column has a fallback value + * Set the fallback value quietly. + * + * @param mixed $fallback + * @return void + */ + protected function setFallback(mixed $fallback): void + { + $this->fallback = $fallback; + } + + /** + * Check if a fallback value exists. * * @return bool */ public function hasFallback(): bool { - return !\is_null($this->fallback); + return isset($this->fallback); } /** - * Get the fallback value for the column + * Get the fallback value. * * @return mixed */ public function getFallback(): mixed { - return $this->fallback; + return $this->evaluate($this->fallback); } } \ No newline at end of file diff --git a/src/Table/Columns/Concerns/IsPreferable.php b/src/Table/Columns/Concerns/IsPreferable.php index 499252e..c3e4300 100644 --- a/src/Table/Columns/Concerns/IsPreferable.php +++ b/src/Table/Columns/Concerns/IsPreferable.php @@ -22,7 +22,7 @@ trait IsPreferable public function preference(bool $default = false): static { if ($this->isKey()) { - throw KeyCannotBeDynamic::invalid(); + throw KeyCannotBeDynamic::make(); } $this->setPreference(true); $this->setDefaultPreference($default); diff --git a/src/Table/Columns/Exceptions/KeyCannotBeDynamic.php b/src/Table/Columns/Exceptions/KeyCannotBeDynamic.php index f271c2a..12fa76f 100644 --- a/src/Table/Columns/Exceptions/KeyCannotBeDynamic.php +++ b/src/Table/Columns/Exceptions/KeyCannotBeDynamic.php @@ -4,7 +4,7 @@ class KeyCannotBeDynamic extends \Exception { - public static function invalid(): self + public static function make(): self { return new self('The key column cannot be preferenced.'); }