serafim / properties
PHP properties implementation
Installs: 9 075
Dependents: 1
Suggesters: 0
Security: 0
Stars: 79
Watchers: 10
Forks: 4
Open Issues: 2
Requires
- php: ^7.1.3
- psr/simple-cache: ~1.0
- railt/lexer: 1.2.*
- railt/parser: 1.2.*
Requires (Dev)
- phpunit/phpunit: ~7.0
- predis/predis: ^1.1
- railt/compiler: 1.2.*
- symfony/cache: 4.1.*
- symfony/console: 4.1.*
- symfony/var-dumper: 4.1.*
README
PHP Properties implementations based on getters or setters method and used PSR-5 PHPDoc information.
Installation
composer require serafim/properties
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
(orinteger
) - property value are integerbool
(orboolean
) - value are booleanfloat
(ordouble
) - value are floatstring
- value are string or object with__toString
methodnull
(orvoid
) - value are nullableresource
- value are resourceobject
- value can be any objectmixed
- no type checkingcallable
- value can be string, instance of \Closure, array with 2 args or object with__invoke
methodscalar
- value cannot be an objectcountable
- value can be a countable (array or object providedCountable
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 arrayClass[]
- value is type of array or instance of \Traversablescalar[]
- value is type of array or instance of \TraversableCollection<>
- value is type of array or instance of "Collection" and \TraversableCollection<T>
- value is type of array or instance of "Collection" and \TraversableCollection<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);