[PHP] Type-Hinting für elementare Datentypen

[PHP] Type-Hinting für elementare Datentypen

Hallo Tutorianer,

es gibt eine Sache, die mich stets in PHP genervt hat. Es geht dabei darum, dass ich in eigenen Funktionen immer erst überprüfen muss, ob die übergebenen Werte den von mir erwarteten Datentypen haben. In anderen Sprachen wird das über Type-Hinting gelöst, was jedoch in PHP nur schwach ausgeprägt ist (Objekte, Arrays und ab Version 5.4 auch Callables). Deshalb habe ich nach einer Lösung gesucht, um dies auch für die elementaren Datentypen (Boolean, Integer, Double, String, Resource) zu ermöglichen, und bin dabei auf einen fünf Jahre alten Beitrag auf den PHP-Seiten gestoßen. Da den meisten wohl diese Möglichkeit bisher unbekannt war, und die dort beschriebene Lösung noch optimiert werden konnte, habe ich eine eigene Lösung entwickelt, die ich euch hiermit präsentieren will, damit ihr sie auch selber nutzen könnt.[PRBREAK][/PRBREAK]

PHP:
<?php
  #
  # LICENSE: "THE BEER-WARE LICENSE" (Revision 42)
  # <gregor.mitzka@gmail.com> wrote this file. As long as you retain this notice you
  # can do whatever you want with this stuff. If we meet some day, and you think
  # this stuff is worth it, you can buy me a beer in return Gregor Mitzka
  # 
  # @package      PHP type-hinting for primitive data types
  # @author       Gregor Mitzka <gregor.mitzka@gmail.com>
  # @copyright    2014 (C) Gregor Mitzka
  # @version      1.0
  # @license      The Beer-Ware License
  #
  class TypeHinting {
    const PCRE = '/^Argument (\d+) passed to (?:(\w+)::)?(\w+)\(\) must be an instance of (\w+), (\w+) given/';

    private static $initialized = false;

    #
    # disable instantiation
    #
    final private function __construct() {}
    
    #
    # handle function which get called by the error-handler (registered in the ->initialize function)
    #
    # @param (int) $error_level
    # @param (string) $error_message
    # @return (bool)
    #
    final public static function handle( $error_level, $error_message ) {
      # we only need errors of the type E_RECOVERABLE_ERROR
      if ( $error_level !== E_RECOVERABLE_ERROR ) {
        return false;
      }

      # check if the error message has the expected format, than parse it
      if ( !preg_match( self::PCRE, $error_message, $matched ) ) {
        return false;
      }

      # we only need the expected and given type of the error message
      list( , $hint_argument_index, $hint_class, $hint_function, $hint_expected_type, $hint_given_type ) = $matched;

      # check if the given type matches the expected type
      # e.g. if the expected type is "number" then the given type can be any of "integer" or "double"
      if ( self::validate_type( $hint_expected_type, $hint_given_type ) ) {
        return true;
      }
      
      # the types numeric and callable need a check against the passed value,
      # so we need to get the backtrace, which needs some more time than the other comparisons
      # (callable is a pre-defined type-hint since PHP 5.4)
      if ( self::validate_complex_type( (int) $hint_argument_index, $hint_class, $hint_function, $hint_expected_type ) ) {
        return true;
      }

      # handle the error message if the given type does not match the expected type
      # translate the matched type into a standarized version, e.g. "int" to "integer" and "float" to "double"
      return self::handle_error( self::translate_type( $hint_expected_type ), $error_message, $error_level );
    }
    
    #
    # defines what happens if a type-error occured
    #
    # @param (string) $expected_type: expected type from the function definition
    # @param (string) $error_message: error message of the catched error
    # @param (int) $error_level: error level of the catched error
    # @return (bool)
    # @throws InvalidArgumentException
    #
    protected static function handle_error( $expected_type, $error_message, $error_level ) {
      if ( $expected_type === false ) {
        throw new InvalidArgumentException( $error_message, $error_level );
      }
      
      switch ( $expected_type ) {
        case 'number':
          $replacement = 'a number';
          break;
        case 'scalar':
          $replacement = 'a scalar';
          break;
        case 'numeric':
          $replacement = 'a numeric value';
          break;
        case 'callable':
          $replacement = 'callable';
          break;
        default:
          $replacement = 'of the type ' . $expected_type;
          break;
      }
      
      # replace the string "an instance of <type>" with "of the type <type>"
      throw new InvalidArgumentException( preg_replace( '/(an instance of (?:\w+))/', $replacement, $error_message ), $error_level );
    }

    #
    # initialize the extended type hinting for PHP
    # check if this happend before else register the handle function
    #
    final public static function initialize() {
      self::$initialized or (
        self::$initialized = true and set_error_handler( __CLASS__ . '::handle', E_RECOVERABLE_ERROR )
      );
    }
    
    #
    # translate a type to its standarized version
    # e.g. "int" to "integer" and "float" to "double"
    #
    # @param (string) $type: type name
    # @return (string): standarized type name
    #
    final private static function translate_type( $type ) {
      switch ( $type ) {
        case 'boolean':
        case 'bool':
          return 'boolean';
        case 'integer':
        case 'int':
          return 'integer';
        case 'double':
        case 'float':
        case 'real':
          return 'double';
        case 'string':
          return 'string';
        case 'resource';
          return 'resource';
        case 'number':
          return 'number';
        case 'scalar':
          return 'scalar';
        case 'numeric':
          return 'numeric';
        case 'callable':
          return 'callable';
      }
      
      return false;
    }
    
    #
    # check if the given type matches the expected type
    #
    # @param (string) $expected_type: name of the expected type
    # @param (string) $given_type: name of the given type
    # @return (bool): true if it matches, else false
    #
    final private static function validate_type( $expected_type, $given_type ) {
      switch ( $expected_type ) {
        case 'boolean':
        case 'bool':
          return ( $given_type === 'boolean' );
        case 'integer':
        case 'int':
          return ( $given_type === 'integer' );
        case 'double':
        case 'float':
        case 'real':
          return ( $given_type === 'double' );
        case 'string':
          return ( $given_type === 'string' );
        case 'resource':
          return ( $given_type === 'resource' );
        case 'number':
          return ( $given_type === 'integer' || $given_type === 'double' );
        case 'scalar':
          return (
            $given_type === 'boolean' ||
            $given_type === 'integer' ||
            $given_type === 'double'  ||
            $given_type === 'string'
          );
        # pseudo-type for every type
        case 'mixed':
          return true;
      }
      
      return false;
    }
    
    #
    # check if the passed values are either "numeric" or "callable"
    #
    # @param (int) $argument_index: index of the argument with the wrong value
    # @param (string) $class_name: name of the class where the error occured
    # @param (string) $function_name: name of the function where the error occured
    # @param (string) $expected_type: expected type (numeric or callable)
    # @return (bool) true if the expected type passes the value comparison, else false
    #
    final private static function validate_complex_type( $argument_index, $class_name, $function_name, $expected_type ) {
      # break if the expected type is neither callable nor numeric
      # (so we need not to call "debug_backtrace")
      if ( $expected_type !== 'callable' && $expected_type !== 'numeric' ) {
        return false;
      }
      
      $trace = debug_backtrace();
      
      # try to find the call of the function $function_name (in class $class_name if it's a method call)
      foreach ( $trace as $step ) {
        if ( $function_name === $step[ 'function' ] ) {
          if ( !array_key_exists( 'class', $step ) || $class_name === $step[ 'class' ] ) {
            # get the argument value with the wrong type
            $argument = $step[ 'args' ][ $argument_index - 1 ];

            switch ( $expected_type ) {
              case 'numeric':
                return is_numeric( $argument );
              case 'callable':
                return is_callable( $argument );
            }
          }
        }
      }
      
      return false;
    }
  }

Die Idee, die dahinter steckt, ist, dass PHP einen Catchable Error wirft, wenn ein Wert nicht einer entsprechenden Klasse entspricht. Wie der Name schon sagt, kann man diesen Fehler auffangen und in einem Errorhandler abarbeiten. In diesem überprüfe ich – basierend auf der Fehlermeldung –, ob der übergebene Wert der übergebenen Pseudoklasse entspricht. Wenn dies der Fall ist, verwerfe ich die Fehlermeldung. Ansonsten wird eine InvalidArgumentException geworfen.

Außerdem kann man auch noch folgende Datentypen angeben: numeric (also alles, was wie eine Zahl aussieht), scalar (also Boolean, Integer, Double und String) und callable. Letzteres ist seit PHP-Version 5.4 direkt implementiert und dient somit hier nur noch dafür, dass auch alle PHP-Versionen unterhalb von 5.4 dies behandeln können.

Die Klasse kann außerdem erweitert werden, weshalb insbesondere die Methode "handle_error" überschrieben werden kann, um eine eigene Fehlerbehandlung zu definieren.

Damit dies alles funktioniert, muss die Klasse nur eingebunden und wie folgt aufgerufen werden:
PHP:
TypeHinting::initialize();
Es werden folgende Datentypangaben unterstützt:
  • boolean / bool
  • integer / int
  • double / float / real
  • string
  • resource
  • number
  • scalar
  • numeric
  • callable

Beispiel
PHP:
class Foo {
  public function plus( numeric $a, numeric $b ) {
    return (float) $a + (float) $b;
  }

  public function hello( string $name ) {
    return "Hello {$name}!";
  }
}

$foo = new Foo;
$foo->plus( 5, "-7" ); // returns -2.0
$foo->plus( 4.3, "foo" ); // throws InvalidArgumentException for argument 2

$foo->hello( "Peter" ); // returns "Hello Peter!"
$foo->hello( 5 ); // throws InvalidArgumentException

Seite des Projekts: https://github.com/MeiKatz/php-type-hinting
Autor
Parantatatam
Aufrufe
1.913
First release
Last update
Bewertung
0,00 Stern(e) 0 Bewertungen
Zurück