custom-d / laravel-helpers
A laravel helpers
Installs: 9 429
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 8
Forks: 0
Open Issues: 0
Requires
- php: ^8.2
- illuminate/notifications: ^9.0|^10.0|^11.0
- illuminate/support: ^9.0|^10|^11.0
Requires (Dev)
- filament/filament: ^3.2
- nunomaduro/larastan: ^1.0|^2.0
- orchestra/testbench: ^7.0|^8.0|^9.0
- phpsa/laravel-api-controller: *
- phpunit/phpunit: ^9.0|^10.0
- dev-master
- v5.3.1
- v5.3.0
- v5.2.2
- v5.2.1
- v5.2.0
- v5.1.0
- v5.0.0
- 4.x-dev
- v4.16.0
- v4.15.0
- v4.14.0
- v4.13.1
- v4.13.0
- v4.12.0
- v4.11.0
- v4.10.0
- v4.9.1
- v4.9.0
- v4.8.0
- v4.7.0
- v4.6.1
- v4.6.0
- v4.5.0
- v4.4.1
- v4.4.0
- v4.3.0
- v4.2.0
- 4.2.0-a.1
- v4.1.1
- v4.1.0
- v4.0.0
- v3.2.0
- v3.1.0
- v3.0.0
- v2.0.0
- v1.4.1
- v1.4.0
- v1.3.0
- v1.2.2
- v1.2.1
- v1.2.0
- v1.1.0
- v1.0.1
- v1.0.0
- dev-feat/docs-for-http-recording
- dev-feat/small-truncation-of-key-case-mapping
- dev-release/4.x
- dev-updated-value-object
- dev-value_objects
- dev-enhanced_exception
- dev-carbon_helpers_month_year
- dev-feat_from_key_or_model
- dev-feat/http-recording-save-status-and-headers
- dev-test_recording
- dev-feat-date-manipulation
- dev-6-signed-requests-cross-site
- dev-josh-master-patch-10865
- dev-4-seedspermissions-cache-breaks-some-seeders-in-tests
- dev-craig.smith-master-patch-26757
- dev-feat_role_seeder
- dev-cd-make-user-command
- dev-2-recaptcha-validation-rule-for-requests
- dev-feat/user_timezone
- dev-docs-fix-permission-example
- dev-feat/lara-9
This package is auto-updated.
Last update: 2024-04-09 03:43:15 UTC
README
Laravel Helpers
Collection of helpers for re-use accross a few of our projects
- Laravel Helpers
Installation
Install via composer
composer require custom-d/laravel-helpers
Upgrade V2 to V3
- ViewAny plicy now checks for a viewAny permission and not list for the viewAny permission check
- Dropped support for php 7.3 & 7.2
- Dropped support for Laravel 6 & 7
- marked execute helper as deprecated
- fixed Model::orWhereNotNullOrEmpty method to do correct query
Crud Policy Trait
by using the CustomD\LaravelHelpers\Models\Policies\CrudPermissions
trait in your model policy along side Spatie role permissions using wildcard permissions
you can have your policy look like:
namespace App\Models\Policies; use App\Models\Policies\Traits\CrudPermissions; use Illuminate\Auth\Access\HandlesAuthorization; class UserPolicy { use HandlesAuthorization; use CrudPermissions; }
and it will check for the following permissions:
- user.viewAny (list is v2 and earlier)
- user.view
- user.create
- user.update
- user.delete
- user.restore
for user locked based policy permissions you can add the following method to your model:
userHasPermission(User $user): bool
Helpers
execute - this helper runs an execute action on an action file with dependancy injection on the contructor
execute(Action::class, $param, $param2);
execute(Action::class);
//resolves as
$app->make(Action::class)->execute(...)
If you discover any security related issues, please email instead of using the issue tracker.
DB Macros
Null Or Empty
when dealing with some of our legacy databases we have some columns where the entry is either null or empty and these macros allow you to query this without the double entries:
Model::whereNullOrEmpty('column_name'); //generates select * where 1=1 and (column_name is null or column_name = '') Model::orWhereNullOrEmpty('column_name'); //generates select * where 1=1 or (column_name is null or column_name = '') Model::whereNotNullOrEmpty('column_name'); //generates select * where 1=1 and (column_name is not null and column_name != '') Model::orWhereNotNullOrEmpty('column_name'); //generates select * where 1=1 or (column_name is not null and column_name != '') Model::whereNullOrValue('column_name', [$operator],$value, [$boolean]); to check if column null or specific value (follows laravel where specification where operator is optional)
Case insensitive statments
Model::iWhere('col',$value); Model::iWhere('col',$operator,$value); Model::iWhere(['col' => $value]);
Enforced Non Nullable Relations (orFail chain)
function related(){ return $this->hasOne()->orFail(); }
DB Repositories
use of repositories via extending the CustomD\LaravelHelpers\Repository\BaseRepository
abstract
example in the UserRepository.stub.php file
Observerable trait (Deprecated)
adding this trait to your models will automatically look for an observer in the app/Observers folder with the convension {model}Observer as the classname,
you can additionally/optionally add
protected static $observers = [ ...arrayOfObservers]
to add a additional ones if
Replace this with
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
use App\Observers\UserObserver;
#[ObservedBy(UserObserver::class)]
#[ObservedBy(AnotherUserObserver::class)]
class User extends Model
{
//
}
Record or Fake HTTP Calls
The RecordsOrFakesHttpCalls
trait will allow you to record or fake http calls in your tests. This is useful for testing external api calls without actually calling them.
Add the trait to your PHPUnit test file, ensure the tests/stubs/
directory exists, and then wrap your test code in a callable:
public function test_external_api() { // $this->record = true; // Toggle to create recorded files $this->processRecordedTest( 'test_external_api', function () { // Any HTTP calls made by MyServiceClass will be recorded or returned from recorded responses, depending on `$this->record` above. $result = resolve(MyServiceClass::class)->execute('foo'); $this->assertEquals('bar', $result->value); }, 'json' ); }
Date Manipulation
You can set user timezones via the following options:
- optionally create a migration with:
Schema::table('users', function (Blueprint $table) {
$table->string('timezone', 40)->nullable();
});
- in user model:
pubic function timezone(): Attribute
{
return Attribute::get(fn($value) => $value ?? config('app.user_timezone'));
}
Additionally you can set defaults on the timezone via the attributes method or a setter or even in the migration.
-
in your app config file add the
user_timezone
parameter. -
add the UserTimeZone middleware to your api middleware list.
You can now access the current requests timezone via config('request.user.timezone')
Date(Carbon) Helpers attached to above:
methods available:
setUserTimezone(string $timezone) : Static
- sets the users timezone (default set by helper)getUserTimezone() : string
- gets current users timezonesetSystemTimezone(string $timezone) : Static
- sets system timezone (Default app.timezone)getSystemTimezone(): string
- gets teh current timezonetoUsersTimezone(): Static
- returns carbon instance set to users timezonetoSystemTimezone(): Static
- returns carbon instance set to system timezoneusersStartOfDay(): Static
- returns carbon instance set to start of users day (converts to users timezone => start of day => to systemtime)usersEndOfDay(): Static
- users end of dayusersStartOfWeek(): Static
usersEndOfWeek(): Static
usersStartOfMonth(): Static
usersEndOfMonth(): Static
usersStartOfQuarter(): Static
usersEndOfQuarter(): Static
usersStartOfYear(): Static
usersEndOfYear(): Static
parseWithTz(string $time): Static
- parses the time passed using the users timezone unless the timezone is in the timestamphasISOFormat(string $date): bool
- checks if the date is in iso format.
You can also use the CDCarbonDate to create a few different date objects.
Value Objects
Example:
<?php declare(strict_types=1); namespace CustomD\LaravelHelpers\Tests\ValueObjects; use CustomD\LaravelHelpers\ValueObjects\ValueObject; final readonly class SimpleValue extends ValueObject { protected function __construct( public string $value, public int $count = 0 ) { } /** optionally add some validation rules, leave out the method if the type sets are enough **/ public function rules(): array { return [ 'value' => ['string', 'max:250'], 'count' => ['max:99'], ]; } } $simpleValue = SimpleValue::make(value: 'hello World', count: 33);
Or using attributes to make advanced objects.
<?php declare(strict_types=1); namespace CustomD\LaravelHelpers\Tests\ValueObjects; use Illuminate\Support\Collection; use CustomD\LaravelHelpers\ValueObjects\ValueObject; use CustomD\LaravelHelpers\ValueObjects\Attributes\MakeableObject; use CustomD\LaravelHelpers\ValueObjects\Attributes\ChildValueObject; use CustomD\LaravelHelpers\ValueObjects\Attributes\CollectableValue; use CustomD\LaravelHelpers\ValueObjects\Attributes\MapToCase; #[MapToCase('camel')] final readonly class ComplexValue extends ValueObject { public function __construct( #[ChildValueObject(StringValue::class)] readonly public StringValue $value, readonly public array $address, #[ChildValueObject(SimpleValue::class)] readonly public SimpleValue $simpleValue, #[MakeableObject(Constructable::class)] readonly public ?Constructable $constructable = null, #[CollectableValue(SimpleValue::class)] readonly ?Collection $simpleValues = null, ) { } }
Best practice is to use the make option, which will validate, if you use a public constructor it will not.
These should all be marked as READONLY and FINAL.
The attributes available are:
ChildValueObject(valueobectclass)
- which will make a new valueObjectCollectableValue(valueobjectclass)
- which will convert an array to a coollection of the value objectsMakeableObject(class, [?$spread = false])
- will look for a make method or else construct if passed an non object - if spread is true will expand the array else will pass the array as a single argumentMapToCase(('snake|camel|studly'))
- for the fromRequest method
Mapping Valueobject from your Request would be as easy as doing one of the following:
//eiterh in your code where you need it. $object = ValueObject::fromRequest($MyFormRequest, true|false); //defaults to true (validated only values, false will be all from the request); //or add a method to your FormRequest public function getObject(): ValueObject { return ValueObject::fromRequest($this); }
Larastan Stubs
these are temporary only till implemented by larastan
add to your phpstan.neon.dist file
parameters: stubFiles: - ./vendor/custom-d/laravel-helpers/larastan/blank_filled.stub
Filament Plugin
** this is only if you want to deal with user timezones for display, else will be in UTC in the Filament panel **
simply add to your panelProvider
->plugin(UserTimeZonePlugin::make())