sandromiguel/php-throw

PHP package for throwing custom exceptions with ease.

v1.1.0 2024-03-30 16:46 UTC

Requires

• php: >=8.1

Requires (Dev)

• nunomaduro/phpinsights: ^2.11
• phan/phan: ^5.4
• phpmetrics/phpmetrics: ^2.8
• phpspec/phpspec: ^7.5
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^9
• psalm/plugin-phpunit: ^0.18.4
• roave/security-advisories: dev-master
• vimeo/psalm: ^5.22

MIT

• Sandro Miguel Marques

• php
• exceptions

README

PhpThrow (Beta) is a PHP package for throwing custom exceptions with ease.

Features

• Provides custom exception classes with additional functionality.
• Easy to use and integrate into existing projects.

Installation

You can install PhpThrow via Composer:

composer require sandromiguel/php-throw

Usage

Comparing Native and PhpThrow exceptions

The following code shows how to use the native InvalidArgumentException class and the ThrowInvalidArgumentException class to throw an exception if the provided value is less than zero:

Native InvalidArgumentException:

try {
    $value = -5;

    if ($value < 0) {
        throw new InvalidArgumentException('The value must be greater than or equal to 0.');
    }

    // ...
} catch (InvalidArgumentException $e) {
    echo $e->getMessage();
}

ThrowInvalidArgumentException:

try {
    $value = -5;

    ThrowInvalidArgumentException::ifZeroOrNegative($value);

    // ...
} catch (ThrowInvalidArgumentException $e) {
    echo $e->getMessage();
}

ThrowInvalidArgumentException

ThrowInvalidArgumentException extends the built-in InvalidArgumentException and provides helper methods for throwing exceptions related to invalid arguments.

create()

create($message): Creates a new instance of the exception with the given message.

$email = 'not-a-valid-email-address';

try {
    // Validate the email address
    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
        throw ThrowInvalidArgumentException::create('Invalid email address');
    }

    // ...
} catch (ThrowInvalidArgumentException $e) {
    echo $e->getMessage(); // Output: Invalid email address
}

ifZeroOrNegative()

ifZeroOrNegative($value, $message = null): Throws an exception if the numeric value is less than 0.

try {
    ThrowInvalidArgumentException::ifZeroOrNegative(-1);
} catch (\PhpThrow\ThrowInvalidArgumentException $e) {
    echo $e->getMessage(); // Output: The value must be greater than or equal to 0.
}

ifZeroOrNegativeWithValue()

ifZeroOrNegativeWithValue($value, $message = null): Throws an exception if the numeric value is negative, including the value in the error message.

try {
    ThrowInvalidArgumentException::ifZeroOrNegativeWithValue(-1);
} catch (\PhpThrow\ThrowInvalidArgumentException $e) {
    echo $e->getMessage(); // Output: The value -1 must be greater than or equal to 0.
}

You can also use a custom message without the placeholder:

ThrowInvalidArgumentException::ifZeroOrNegativeWithValue(
    -1,
    'Value must be positive'
); // Output: Value must be positive. Provided -1

ThrowPageNotFoundException

ThrowPageNotFoundException is used to handle exceptions when a page is not found.

Example: ThrowPageNotFoundException::forPage

use PhpThrow\ThrowPageNotFoundException;

$page = 'non-existent-page';
ThrowPageNotFoundException::forPage($page); // Throws an exception with the message "The page 'non-existent-page' was not found."

Note: By default, the error code is set to 404. You can change it using the code parameter.

Contributing

Want to contribute? All contributions are welcome. Read the contributing guide.

Questions

If you have questions tweet me at @sandro_m_m or open an issue.

Changelog

See CHANGELOG.md

License

This project is licensed under the MIT License - see the LICENSE file for details

TODO

• Implement additional exception classes and methods for common validations

**~ sharing is caring ~**