langleyfoxall/helpers-laravel

A collection of useful classes to help making Laravel applications easier

2.0.0 2021-04-21 14:51 UTC

Requires

• php: ^7.3||^8.0
• illuminate/database: >=5.0
• illuminate/http: >=5.0
• illuminate/support: >=5.0

Requires (Dev)

• orchestra/testbench: ^5.17.1

LGPL-3.0-only

• Dexter Marks-Barber
• Jordan Hall
• Jared Wheatley

• php
• helpers
• laravel

README

A repository of Laravel specific helper classes to help standardise work. API helpers, converters etc.

Installation

The Langley Foxall Helpers Laravel package can be easily installed using Composer. Just run the following command from the root of your project.

composer require langleyfoxall/helpers-laravel

If you have never used the Composer dependency manager before, head to the Composer website for more information on how to get started.

Helpers

• Models
• IsRelatedTo
• Enum
• ApiResponse
• Response
• ResponseCache
• IdentifiedByUUID

Models

The Models helper offers helpful functions to do with Eloquent Models.

Methods

All methods can be called statically.

• all
• utf8EncodeModel
• getColumns
• getNextId
• areRelated
• randomByWeightedValue

all

Get a Collection of all models.

Example Usage

$collection_of_models = Models::all()

Key	Details
Parameters	None
Throws	None
Returns	Collection

utf8EncodeModel

Encodes attribute values of a single model to UTF-8, and returns the model.

Example Usage

$encoded_user = Models::utf8EncodeModels($user)

Key	Details
Parameters	Model
Throws	None
Returns	Model

utf8EncodeModels

Encodes attribute values of mutliple models to UTF-8, and returns a collection of model.

Example Usage

$collection_of_encoded_users = Models::utf8EncodeModels($users)

Key	Details
Parameters	A Collection of Models
Throws	None
Returns	A Collection of Models

getColumns

Get an Array of the database columns for a given model.

Example Usage

$columns = Models::getColumns($user)

Key	Details
Parameters	Model
Throws	None
Returns	Array

getNextId

Get the next auto incremented ID for a model.

Example Usage

$next_id = Models::getNextId($user)

Key	Details
Parameters	Model
Throws	Exception
Returns	Integer

areRelated

Check if an unspecificed number of models are related to each other.

Example Usage

If an instance of Model is passed, then areRelated will attempt to get a plural then singular method from the model that can then be used by the previous model in the sequence to confirm that they are related. If an array is passed, it expects the first element to be an instance of Model and the second to be a string which is the relationship method

A NotRelatedException is also provided to be used in an application.

$related = Models::areRelated($user, $post, [$comment, 'comments'])

Key	Details
Parameters	Mutliple Models or Mutliple Array
Throws	Exception or InvalidArgumentException
Returns	Boolean

randomByWeightedValue

Takes a collection of Model's and returns one based upon a weighted column. It can also take a maxCap to simulate higher odds.

It should be noted when passing a maxCap you should pass in a desired return value if none of the items in the models list were hit.

Example Usage

$prizes = Prizes::all();
$selectedPrize = Models::randomByWeightedValue($models, 'chance');

//returns a prize as if the 'chance' column related to {$chance}/10,000,000 - if none are hit it will return null.
$selectedPrize = Models::randomByWeightedValue('App\Models\Prize', 'chance', 10000000, null);

Key	Details
Parameters	A Collection of Models or a string representation of a Model, column, maxCap = null, ifLose = null
Throws	None
Returns	Model or an object

IsRelatedTo

The IsRelatedTo helper is a trait that allows quick and easy access to the areRelated method in the Models helper.

Methods

• isRelatedTo

isRelatedTo

Check if a single model is related to the parent model.

Example usage

class User extends Model {
    use IsRelatedTo;
}

$related = $user->isRelatedTo($post)

Key	Details
Parameters	Model or Array
Returns	Boolean

Enum

The Enum helper is a trait that provides helpers for dealing with enum classes.

Methods

• all
• valid

all

Return an array of all values.

Example usage

class UserType
{
    use \LangleyFoxall\Helpers\Traits\Enum;

    const ADMIN = 'admin';
    const USER = 'user';
}

class User extends Eloquent
{
    public function getValidTypes()
    {
        return UserType::all();
    }
}

Key	Details
Parameters
Returns	Array

valid

Check if a provided value is a valid value of the enum class.

Example usage

class UserType
{
    use \LangleyFoxall\Helpers\Traits\Enum;

    const ADMIN = 'admin';
    const USER = 'user';
}

class User extends Eloquent
{
    public function setTypeAttribute(string $type)
    {
        if (!UserType::valid($type)) {
            throw new InvalidUserType;
        }

        $this->type = $type;
    }
}

Key	Details
Parameters	String
Returns	Boolean

ApiResponse

The ApiResponse helper standardizes an API response. Always containing the same fields:

Key	Type	Description
status	Integer	status is used for accessibility when the response cannot access the HTTP client, such as axios
success	Boolean	success is a boolean to signify that an operation was successful or not
error	NULL, String or Array	error is used to describe errors or warnings that have happened during the operation
data	NULL or Array	data should contain the main resource information
meta	NULL or Array	meta should contain extra resource information, such as other endpoints that can be used with the current resource

The ApiResponse helper also implements ArrayAccess which can be used to transform data easily. Example usage can be found here.

After building up the response, before returning it from a Controller, you must call json.

Methods

• success
• error
• data
• meta
• status
• json
• cache

success

Create a successful response instance.

Example Usage

None of the parameters are required.

$api_response = ApiResponse::success($data, $meta, $status)

Key	Details
Parameters	data, meta, status
Returns	ApiResponse

error

Create a unsuccessful response instance.

Example Usage

None of the parameters are required.

$api_response = ApiResponse::error($errors, $status)

Key	Details
Parameters	error, status
Returns	ApiResponse

data

Set the data to be returned in the response.

Example Usage

None of the parameters are required.

$api_response->data($data)

Key	Details
Parameters	NULL or Array
Returns	ApiResponse

meta

Set the meta to be returned in the response.

Example Usage

None of the parameters are required.

$api_response->meta($meta)

Key	Details
Parameters	NULL or Array
Returns	ApiResponse

status

Set the response status code.

Example Usage

$api_response->status($status)

Key	Details
Parameters	Integer
Returns	ApiResponse

json

Get the JSON response object

Example Usage

$json_response = $api_response->json()

Key	Details
Parameters	None
Returns	JsonResponse

cache

Cache the current ApiResponse data for use in a later request. By default if the cache currently has data in it the data will not be overwritten. Using forceOverwrite it can be overwritten, this defaults to false. cache must be called after data is set.

Example Usage

lifespan accepts an Integer value for the lifespan in minutes or a Carbon time when the cache will be cleared. cache must be an instantiated ResponseCache.

ApiResponse::success($data)->cache(1, $cache)->json();

Key	Details
Parameters	lifespan, cache, forceOverwrite (Optional)
Returns	ApiResponse

Response

The Response helper should only be used if, for whatever reason, API endpoints use the same Controller methods as web URIs. This helper will check to see if the request is expecting JSON or not and return the right response.

Key	Type	Description
request	Request	request is used when it comes to deciding which response to return to the client
type	String	type is a string, "success" or "error", which will determine which API Response is returned
message	NULL, String or String	message is used for a redirect back with a session variable (web) or an error message (API)
data	NULL or Array	data should contain the main resource information
meta	NULL or Array	meta should contain extra resource information, such as other endpoints that can be used with the current resource
status	Integer	status is used for accessibility when the response cannot access the HTTP client, such as axios
uri	String	uri is used when wanting to redirect rather than back with a web response

Methods

None of the following methods can be called statically. When instansiating a new instance of Response a Request object is required.

• success
• error
• type
• message
• data
• meta
• status
• redirect
• end

success

Create a successful response.

Example Usage

None of the parameters are required.

$response = (new Response($request)->success($message, $data, $meta, $status)

Key	Details
Parameters	message, data, meta, status
Returns	Response

error

Create a unsuccessful response.

Example Usage

None of the parameters are required.

$response = (new Response($request)->success($message, $status)

Key	Details
Parameters	message, status
Returns	Response

type

Set the response type. While error and success are not aggressively checked the type will default to success if not error.

Example Usage

$response = (new Response($request)->success($type)

Key	Details
Parameters	type
Returns	Response

message

Set the message to be displayed if an error occurs or a back is triggered.

Example Usage

$response = (new Response($request)->message($message)

Key	Details
Parameters	message
Returns	Response

data

Set the data to be returned in an successful ApiResponse.

Example Usage

None of the parameters are required.

$response = (new Response($request)->data($data)

Key	Details
Parameters	data
Returns	Response

meta

Set the meta to be returned in an successful ApiResponse.

Example Usage

None of the parameters are required.

$response = (new Response($request)->meta($meta)

Key	Details
Parameters	meta
Returns	Response

status

Set the status to be returned in an ApiResponse. This will be overwritten if called before success or error.

Example Usage

$response = (new Response($request)->status($status)

Key	Details
Parameters	status
Returns	Response

redirect

Set the redirect URI to be called rather than redirecting back.

Example Usage

None of the parameters are required.

$response = (new Response($request)->redirect($uri)

Key	Details
Parameters	uri
Returns	Response

end

Return the expected response.

Example Usage

$expected_response = (new Response($request)->end()

Key	Details
Parameters	None
Returns	RedirectResponse or JsonResponse

ResponseCache

The ResponseCache helper simplifies caching API Responses taking into account differing request parameters and user accounts. Unique caches are generated based on the request route, method, parameters and user.

Key	Type	Description
request	Request	The request that the cache will be for.
userSpecific	Boolean	userSpecific specifies if the response is cached for individual users or if all users share one cache. Important: Misuse of userSpecific can lead to massive inefficiencies and security flaws. If a response is the same for any user userSpecific should be set to false so that a new cache is not created for every user. If a response contains data pertaining to that user userSpecific should be set to true so that users do not receive someone else's cached data.
excludeParams	(Optional) NULL or Array	Since request parameters are likely to change the data generated a seperate cache is generated for different sets of parameters so that the correct data is returned. However some parameters do not change the data generated so a new cache does not need to be generated when they change. Adding these parameters to excludeParams will mean that they are ignored.

Methods

None of the following methods can be called statically.

• hasData
• getData
• cacheData
• getKey
• clear

hasData

Returns if the current cache has any data.

Example Usage

if($cache->hasData()){...

Key	Details
Parameters	None
Returns	Boolean

getData

Returns the data currently in the cache, returns null if empty.

Example Usage

$data = $cache->getData();

Key	Details
Parameters	None
Returns	Mixed

cacheData

Saves data to the cache. Any data currently in the cache will be overwritten/

Example Usage

data can be any serializable data, lifespan can be minutes as an Integer or a Carbon time that the cache will expire at.

$cache->cacheData(["Hello" => "World"], Carbon:now()->addSeconds(4404));

Key	Details
Parameters	data, lifespan
Returns	None

getKey

Returns the unique key for the cache generated based on the request path, method, parameters and user.

Example Usage

$key = $cache->getKey();

Key	Details
Parameters	None
Returns	String

clear

Clears the data for the given cache.

Example Usage

$cache->clear();

Key	Details
Parameters	None
Returns	None

Usage with ApiResponse

A cache can be created from anApiResponse automatically by using the cache function on it. It will only cache new data if the cache does not contain data. See documentation here.

Example Usage

$cache = new ResponseCache($request, false);

if($cache->hasData()){
    $data = $cache->getData();
}else{
    $data = computationallyExpensiveFunction();
}

return ApiResponse::success($data)->cache(1, $cache)->json();

IdentifiedByUUID

The IdentifiedByUUID trait allows you to easily use V4 UUIDs over incrementing primary keys.

Example Usage

Change your migrations to allow the use of a UUID.

public function up()
{
    Schema::create('demos', function (Blueprint $table) {
        $table->uuid('id')->primary();
        $table->timestamps();
    });
}

Use the trait.

class Demo extends Model
{
    use IdentifiedByUUID;
}

Now when the model is saved, it will automatically be populated with a V4 UUID.