README

PHP Properties implementations based on getters or setters method and used PSR-5 PHPDoc information.

• Installation
• Introduction
• Properties Usage
  • Readonly Properties
  • Writeonly Properties
  • Getters And Setters
  • Autocomplete
• Type Hints
  • Primitive Type Hints
  • Arrays And Generics
  • Conjunction And Disjunction
• Production Mode

Installation

composer require serafim/properties

Package on packagist.org

Introduction

Properties provide the ability to control the behavior of setting and retrieving data from an object fields.

There are no properties at the language level, but they can be implemented with the some additional functionality.

For example:

class MyClass
{
    protected $a = 23;

    public function __get($field)
    {
        return $this->$field;
    }
}

$dto = new MyClass();
echo $dto->a; // 23
$dto->a = 42; // Cannot access protected property MyClass::$a

This code example does not provide type-hint and autocomplete. Using magic without the ability to control it is always a bad option. ...well, it looks awful %)

We can fix some problems using PSR-5. In this case, we can add a docblock.

/**
 * @property-read int $a
 */
class MyClass
{
    // ...

But this docblock only adds information for the IDE and does not affect the code itself. At the same time, you should always keep it up to date.

But wait! We have another problem.

$dto = new MyClass();
echo isset($dto->a); // false

This is obviously a bug. We still need to add __isset, __unset and __set support.

It's damn awful!!111

Properties Usage

Now let's see what the serafim/properties package provides.

/**
 * @property $a
 */
class MyClass
{
    use Serafim\Properties\Properties;
    
    protected $a = 23;
}

$dto = new MyClass();
$dto->a;      // 23
$dto->a = 42; // Ok
$dto->a;      // 42

Readonly Properties

To indicate that the type should be readonly use @property-read annotation.

/**
 * @property-read $a
 */
class MyClass
{
    use Serafim\Properties\Properties;
    
    protected $a = 23;
}

$dto = new MyClass();
$dto->a;      // 23
$dto->a = 42; // Error: Property MyClass::$a is readonly

Writeonly Properties

To indicate that the type should be readonly use @property-write annotation.

/**
 * @property-write $a
 */
class MyClass
{
    use Serafim\Properties\Properties;
    
    protected $a = 23;
}

$dto = new MyClass();
$dto->a = 42; // 42
$dto->a;      // Error: Property MyClass::$a is writeonly

Getters And Setters

For getter or setter override just declare get[Property] (is[Property] for bool values will be works too) or set[Property] methods.

/**
 * @property-read int $a
 */
class MyClass
{
    use Serafim\Properties\Properties;
    
    protected $a = 23;

    protected function getA() 
    {
        return $this->a + 19;
    }
}

$dto = new MyClass();
echo $dto->a; // 42 (because 23 + 19 = 42)
$dto->a = 42; // Error: Property is read-only (@property-read doc declaration)

Setter:

/**
 * @property-write string $anotherProperty
 */
class Some 
{
   // ... 
   protected $anotherProperty = 'some';
   
    /**
     * @param string $newVal
     */
   public function setAnotherProperty($newVal) 
   {
       // Just example
       if (mb_strlen($newVal) > 4) {
           throw new InvalidArgumentException('...');
       }
       
       $this->anotherProperty = $newVal;
   }
}

Autocomplete

All these annotations fully work in the IDE, including autocomplete and highlighting incorrect behavior.

Type Hints

All properties with writeable behavior will be "type checkable".

/**
 * @property int|null $a
 */
class Some
{
    use Serafim\Properties\Properties;
    
    protected $a; 
}

//

$some = new Some;
$some->a = 23; // Ok
$some->a = null; // Ok
$some->a = 'string'; // Error: "TypeError: Value for property Some::$a must be of the type int|null, string given"

Primitive Type Hints

• int (or integer) - property value are integer
• bool (or boolean) - value are boolean
• float (or double) - value are float
• string - value are string or object with __toString method
• null (or void) - value are nullable
• resource - value are resource
• object - value can be any object
• mixed - no type checking
• callable - value can be string, instance of \Closure, array with 2 args or object with __invoke method
• scalar - value cannot be an object
• countable - value can be a countable (array or object provided Countable interface).
• self - value can be object of self class or string with name of self class

self keyword does not available yet: it will be supports in future

• static - value can be instance of self class or string whos are sublass of self

static keyword does not available yet: it will be supports in future

• $this - value can be only object instance of self class

$this keyword does not available yet: it will be supports in future

Arrays And Generics

• array - value is type of array
• Class[] - value is type of array or instance of \Traversable
• scalar[] - value is type of array or instance of \Traversable
• Collection<> - value is type of array or instance of "Collection" and \Traversable
• Collection<T> - value is type of array or instance of "Collection" and \Traversable
• Collection<T,V>- value is type of array or instance of "Collection" and \Traversable

Conjunction And Disjunction

• a|b - means that the value must be type (a or b).
• a&b - means that the value must be type (a and b).
• a|b&c - means that the value must be type (a or (b and c)).

See more: https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types

Production Mode

The code is quite effective, but in the production mode you should use caching. The package implements support for the PSR-16 standard.

$driver = new Psr16CacheDriver(); // Your PSR16 cache driver implementation 

$properties = Serafim\Properties\Bootstrap::getInstance();
$properties->setCacheDriver($driver);