Creating Datatypes in eZ Publish 4

We start our journey through the PHP code with the ymcDatatypeDatetime class, which holds a DateTime object.

The first method is the constructor. It needs a string representing the date as input. The format of the string is the one accepted by the DateTime class respective to the GNU Date command. The second parameter represents the timezone and can be given either as a string or as a DateTimeZone object; it defaults to the PHP data.timezone INI setting.

public function __construct( $dtString = NULL, $tz = NULL )
    {
        if( is_string( $dtString ) )
        {
            if( is_string( $tz ) )
            {
                try{
                    $tz = new DateTimeZone( $tz );
                } catch( Exception $e ) {
                    throw new ymcDatatypeInvalidParams(
                            $tz.' is no valid timezone identifier.'
                    );
                }
            }
            elseif( NULL === $tz )
            {
                $tz = new DateTimeZone( date_default_timezone_get() );
            }
 
            if( !$tz instanceOf DateTimeZone )
            {
                throw new ymcDatatypeInvalidParams(
                        'The second parameter of the constructor needs to be either a '
                        .'valid Timezone string or an instance of DateTimeZone.' );
            }
 
            try
            {
                $this->dateTime = new DateTime( $dtString, $tz );
            }
            catch( Exception $e )
            {
                throw new ymcDatatypeInvalidParams( $dtString.' is no valid DateTime string.');
            }
        }
    }

What I want to point out here are the exceptions used in the constructor, as shown below:

try
            {
                $this->dateTime = new DateTime( $dtString, $tz );
            }
            catch( Exception $e )
            {
                throw new ymcDatatypeInvalidParams( $dtString.' is no valid DateTime string.');
            }

If you try to instantiate a ymcDatatypeDateTime object with invalid data, an exception is thrown. This is no problem, since you can catch the exception and produce the appropriate feedback to the user. The advantage in the code is that the input validation can be reduced to just a few lines in the ymcDatatypeDateTimeType class, similar to the following simplified example:

try{
            $this->content = new ymcDatatypeDateTime( $datestr, $tz );
        }
        catch( ymcDatatypeInvalidParams $e )
        {
            $this->content = NULL;
            return eZInputValidator::STATE_INVALID;
        }
        return eZInputValidator::STATE_ACCEPTED;

Inside the templates, we work with an instance of the ymcDatatypeDateTime class to show the content of the datatype. To get the data out of the object, eZ Publish needs two methods to access the data: attribute and hasAttribute. These two methods do essentially the same thing as the new PHP 5 magic methods __get and __isset. Therefore our methods simply forward the request to those magic methods.

We will discuss the templates and how to retrieve the content later.

The remaining __toString and createFromString methods are needed to serialize and unserialize the object to and from a string that can be saved in the database:

public function __toString()
    {
        if( NULL === $this->dateTime )
        {
            return '';
        }
        return $this->dateTime->format( self::FORMAT_MYSQL_FULL )
              .$this->dateTime->format( self::FORMAT_TIMEZONE_IDENTIFIER );
    }
 
    public static function createFromString( $string )
    {
        if( '' === $string )
        {
            return new self;
        }
        return new self(
            substr( $string, 0, 19 ),
            substr( $string, 19 )
        );
    }