# Traits

Auto-generation note:

🐛 Some traits may use other traits, but due to some issues the used traits are not recognized.

# `NelsonMartell\Collections\CollectionIterator`

Implementa los métodos de la interfaz Iterator para una colección de objetos.


Uses	Nothing

# Description

No description.


Since	`v0.4.0`
Authors	Nelson Martell <nelson6e65@gmail.com>

# Methods

current ( )

public function current(  ) : void

getItem ( ) abstract

protected function getItem( mixed $index ) : void

Parameter	Type(s)	Description
`$index`	`mixed`

key ( )

public function key(  ) : void

next ( )

public function next(  ) : void

rewind ( )

public function rewind(  ) : void

valid ( )

public function valid(  ) : void

# Properties

This trait has not properties.

# `NelsonMartell\PropertiesHandler`

Enables the class to call, implicitly, getter and setters for its properties, allowing to use properties directly.


Uses	Nothing

# Description

Restricts get and set actions for a property if there is not getter/setter definition for that property, by encapsulating the class attributes.

You can customize the properties validation/normalization without the need to call other functions/methods outside the class before to set the value of after outputs.

In addition, the class will be strict: any access to undefined property will be bloqued and informed in dev time.

Also, any property can be restricted to "read-only" or "write-only" from outside the class by simply excluding the setter or getter for that property, respectively.

Usage:

Example 1: Person with normalizations on its name:

<?php
// You can document $name property using: "@property string $name Name of person" in the class definition
class Person implements \NelsonMartell\IStrictPropertiesContainer {
    use \NelsonMartell\PropertiesHandler;

    public function __construct($name)
    {
        $this->setName($name); // Explicit call the setter inside constructor/class
    }

    private $name = ''; // Property. 'private' in order to hide from inherited classes and public

    protected function getName() // Getter. 'protected' to hide from public
    {
        return ucwords($this->name); // Format the $name output
    }

    protected function setName($value) // Setter. 'protected' in order to hide from public
    {
        $this->name = strtolower($value); // Normalize the $name
    }
}

$obj = new Person();
$obj->name = 'nelson maRtElL'; // Implicit call to setter
echo $obj->name; // 'Nelson Martell' // Implicit call to getter
echo $obj->Name; // Throws: InvalidArgumentException: "Name" property do not exists in "Nameable" class.

Example 2: Same as before, but using a property wrapper (not recommended):

<?php
class Nameable implements NelsonMartell\IStrictPropertiesContainer {
    use \NelsonMartell\PropertiesHandler;

    private $_name = ''; // Attribute: Stores the value.
    public $name; // Property wrapper. Declare in order to be detected. Accesible name for the property.

     public function __construct($name)
    {
        unset($this->name); // IMPORTANT: Unset the wrapper in order to redirect operations to the getter/setter

        $this->name = $name; // Implicit call to the setter inside the class
    }

    protected function getName()
    {
        return ucwords($this->_name);
    }

    protected function setName($value)
    {
        $this->_name = strtolower($value);
    }
}

$obj = new Nameable();
$obj->name = 'nelson maRtElL';
echo $obj->name; // 'Nelson Martell'

?>

Example 3: Same as before, but implementing IMagicPropertiesContainer

<?php
use NelsonMartell\IStrictPropertiesContainer;
use NelsonMartell\PropertiesHandler;
use NelsonMartell\IMagicPropertiesContainer;


// Rest of class DocBlock...
// @property string $name Name of person
class Nameable implements IStrictPropertiesContainer, IMagicPropertiesContainer {
    use PropertiesHandler;

    private $_name = ''; // Attribute: Stores the value.

     public function __construct($name)
    {
        $this->name = $name; // Implicit call to the setter inside the class
    }

    protected function getName()
    {
        return ucwords($this->_name);
    }

    protected function setName($value)
    {
        $this->_name = strtolower($value);
    }
}

$obj = new Nameable();
$obj->name = 'nelson maRtElL';
echo $obj->name; // 'Nelson Martell'

?>

Limitations:

You should not define properties wich names only are only different in the first letter upper/lowercase; it will be used the same getter/setter method (since in PHP methods are case-insensitive). In the last example, if you (in addition) define another property called $Name, when called, it will be used the same getter and setter method when you access or set both properties (->Name and ->name).
Only works for public properties (even if attribute and getter/setter methods are not public); this only will avoid the direct use of method ($obj->getName(); // ERROR), but the property value still will be accesible in child classes and public scope ($value = $this->name; // No error).
Getter and Setter methods SHOULD NOT be declared as private in child classes if parent already uses this trait.
Custom prefixes ability (by implementing ICustomPrefixedPropertiesContainer) is not posible for multiple prefixes in multiples child classes by overriding ICustomPrefixedPropertiesContainer methods. If you extends a class that already implements it, if you override any methor to return another prefix, parent class properties may be unaccesible (know bug).
Avoid the use of custom prefixes and use the standard 'get'/'set' instead. If you need to, maybe you could try to rename methods instead first.


Since	`v0.5.0` `v1.0.0`: Auto-detect magic properties defined in class DocBlock.
Authors	Nelson Martell <nelson6e65@gmail.com>
See also	`\NelsonMartell\IMagicPropertiesContainer`

# \NelsonMartell\PropertiesHandler Methods

__get ( )

Gets the property value using the auto-magic method $getterPrefix.$name() (getter), where $name is the name of property and $getterPrefix is 'get' by default (but can be customized).

public function __get( string $name ) : mixed

Parameter	Type(s)	Description
`$name`	`string`	Property name.


See also	`\NelsonMartell\PropertiesHandler::getPropertyGetter()`

__set ( )

Sets the property value using the auto-magic method $setterPrefix.$name() (setter), where $name is the name of property and $setterPrefix is 'set' by default (but can be customized).

public function __set( string $name, mixed $value ) : void

Parameter	Type(s)	Description
`$name`	`string`	Property name.
`$value`	`mixed`	Property value.


See also	`\NelsonMartell\PropertiesHandler::getPropertySetter()`

ensureMethodExists ( ) static deprecated

Ensures that method provided exists in this class.

protected static function ensureMethodExists( string $name ) : string

Parameter	Type(s)	Description
`$name`	`string`	Method name.


Deprecated	Since `v1.0.0`: Implementation moved to Extensions\MethodExtension::ensureIsDefined()
See also	`\NelsonMartell\Extensions\MethodExtension::ensureIsDefined()`

Returns:

Same method name, but validated.

ensurePropertyExists ( ) static deprecated

Ensures that property provided exists in this class.

protected static function ensurePropertyExists( string $name ) : string

Parameter	Type(s)	Description
`$name`	`string`	Property name.


Deprecated	Since `v1.0.0`: Implementation moved to Extensions\PropertyExtension::ensureIsDefined()
See also	`\NelsonMartell\Extensions\PropertyExtension::ensureIsDefined()`

Returns:

Same property name, but validated.

getPropertyGetter ( ) static

Gets the property getter method name.

protected static function getPropertyGetter( string $name, string $prefix = 'get', boolean $useCustom = true ) : string

Parameter	Type(s)	Description
`$name`	`string`	Property name.
`$prefix` optional	`string`	Property getter prefix.
`$useCustom` optional	`boolean`	Check for custom getter prefixes.

Description:

You can customize the getter prefix by implementing ICustomPrefixedPropertiesContainer interface.


Since	`v1.0.0`: Add `$prefix` and `$useCustom` params.
See also	`\NelsonMartell\ICustomPrefixedPropertiesContainer::getCustomGetterPrefix()`

getPropertySetter ( ) static

Gets the property setter method name.

protected static function getPropertySetter( string $name, string $prefix = 'set', boolean $useCustom = true ) : string

Parameter	Type(s)	Description
`$name`	`string`	Property name.
`$prefix` optional	`string`	Property setter prefix.
`$useCustom` optional	`boolean`	Check for custom setter prefixes.

Description:

You can customize the setter prefix by implementing ICustomPrefixedPropertiesContainer interface.


Since	`v1.0.0`: Add `$prefix` and `$useCustom` params.
See also	`\NelsonMartell\ICustomPrefixedPropertiesContainer::getCustomSetterPrefix()`

# \NelsonMartell\PropertiesHandler Properties

This trait has not properties.

This document was automatically generated, from source code comments, using phpDocumentor (opens new window) with the VuePress template (opens new window).

Auto-generated at: 2022-05-03, 10:59 AM

← Interfaces Functions →

# Traits

# NelsonMartell\Collections\CollectionIterator

# Description

# \NelsonMartell\Collections\CollectionIterator Methods

# \NelsonMartell\Collections\CollectionIterator Properties

# NelsonMartell\PropertiesHandler

# Description

# \NelsonMartell\PropertiesHandler Methods

# \NelsonMartell\PropertiesHandler Properties

# `NelsonMartell\Collections\CollectionIterator`

# Methods

# Properties

# `NelsonMartell\PropertiesHandler`