DataTypes support

[partikule]

What about DataTypes support, in a way looking like the Segments support ?

[senaranya]

Can you elaborate a little, or give an example?

[partikule]

Sure.
Let's take the XCN datatype (https://hl7-definition.caristix.com/v2/HL7v2.5.1/DataTypes/XCN) :
It looks like a segment, it is used by parent segments, but the difference with a segment is that it has no name (the first field can be filled)
Currently, the datatypes are not implemented, so the only way to add them to a segment is to pass an array of all the fields of the wished datatype.

My idea :

<?php

namespace App\Service\HL7;

/**
 *
 */
class DataType
{
    protected $fields;

    public function __construct(array $fields = null)
    {
        $this->fields = [];

        if (\is_array($fields)) {
            foreach ($fields as $i => $value) {
                $this->setField($i + 1, $value);
            }
        }
    }

    public function setField(int $index, $value = ''): bool
    {
        if ($this->isValueEmpty($value)) {
            return false;
        }

        // Fill in the blanks...
        for ($i = \count($this->fields); $i < $index; $i++) {
            $this->fields[$i] = '';
        }

        $this->fields[$index] = $value;

        return true;
    }

    private function isValueEmpty($value): bool
    {
        if (is_array($value)) {
            return empty($value);
        }

        if ((string) $value === '0') { // Allow 0
            return false;
        }

        return ! $value;
    }

    /**
     * Remove any existing value from the field
     *
     * @param int $index Field index
     * @return void
     */
    public function clearField(int $index): void
    {
        $this->fields[$index] = null;
    }

    public function getField(int $index)
    {
        return $this->fields[$index] ?? null;
    }

    public function size(): int
    {
        return \count($this->fields) ;
    }

    public function getFields(int $from = 0, int $to = null): array
    {
        if (!$to) {
            $to = \count($this->fields);
        }
        return \array_slice($this->fields, $from, $to - $from + 1);
    }
}

This way, the developer has just to extend DataType and add one to the parent segment by using :

$rol = new ROL();

// XCN extends Datatype
$xcn = new XCN();
$xcn->setFamilyName('Cloooonaye');
$xcn->setGivenName('Djorge');

$rol->setRolePerson($xcn->getFields());

[senaranya]

Thank you for the explanation. This looks quite interesting. If it can be implemented without any changes to the existing code or functionality then feel free to take it up. Please don't forget to add tests. Otherwise I can get to it if you can wait for a few more weeks

[partikule]

As we have a current running project with an hospital, we already started to implement it.
Sadly, we cannot wait.
I wanted to keep as close as possible to your library, but at the end, we has the need to fork it internally to be able to develop quickly our middlewares between our internal objects and incoming hospital HL7 messages.
Therefor, we made a lot of modifications (eg. return $this from Segment::setField(), be able to add Datatypes objects to segments, eg: $segment->setField(XTN $xtn), check datatypes validity with Tables classes and other things like the handle of repeatables :

    /**
     * @param int $index
     * @param string|array|mixed $value
     * @param bool $replace
     * @return $this
     */
    public function setRepeatableField(int $index, $value='', bool $replace=false): self
    {
        // Do not allow changing 0th index, which is the name of the segment
        if ($index === 0 || $this->isValueEmpty($value))
            return $this;

        $this->fillBlanks($index);

        if ($replace || empty($this->fields[$index]))
            $this->fields[$index] = [];

        $this->fields[$index][] = gettype($value) === 'object'
            ? $value->getFields()
            : $value;

        return $this;
    }

    /**
     * @param int $position
     * @param string $dataTypeName
     * @return mixed|null
     * @throws Exception
     */
    public function getDataTypeField(int $position, string $dataTypeName)
    {
        if (empty($this->getField($position)))
            return null;

        $className = __NAMESPACE__ .  "\\DataTypes\\$dataTypeName";
        if ( ! class_exists($className))
            throw new Exception('The DataType ' .$className .' is not defined');

        return new $className($this->getField($position));
    }

    public function isRepeatablePosition(int $index): bool
    {
        return in_array($index, $this->repeatableIndexes);
    }


    /**
     * Returns an array of given datatype for one segment's position.
     * Called by Segment instance getters
     * Important about :
     *  Segment fields containing repeatable datatypes can contain [0...n] datatypes as arrays
     *  If the position contains only one datatype, it will be represented by a simple array and not an array of datatypes.
     *  Example of result of PID::getField(11) with 1 and 2 adresses (XAD) inside one PID (see: PID::getPatientAddress).
     *  1 address :     ["14 rue Fourier", "", "Nantes", "Loire-Atlantique", "44000", "FRA", "H"]
     *  2 addresses :   [
     *                      ["14 rue Fourier", "", "Nantes", "Loire-Atlantique", "44000", "FRA", "H"],
     *                      ["12 rue des plantes", "", "Nantes", "Loire-Atlantique", "44000", "FRA", "VA"],
     *                  ]
     *  This is handled by the Segment::hasSingleValue() method
     *  
     * @param int $position
     * @param string $dataTypeName
     * @return array|null
     * @throws Exception
     */
    public function getDatatypeList(int $position, string $dataTypeName): ?array
    {
        $result = [];

        if (empty($this->getField($position)))
            return $result;

        $className = __NAMESPACE__ .  "\\DataTypes\\$dataTypeName";
        if ( ! class_exists($className))
            throw new Exception('The DataType ' .$className .' is not defined');

        try {
            $content = $this->getField($position);

            if ($this->isRepeatablePosition($position) && $className::hasSingleValue($content))
                $content = [$content];

            if ($this->isRepeatablePosition($position)) {
                foreach($content as $value)
                    $result[] = new $className($value);
            }
            else {
                $result[] = new $className($content);
            }
        }
        catch (Exception $e) {
            throw new Exception($dataTypeName .' : ' . $e->getMessage());
        }

        return $result;
    }

Some example of what we done.
Could be inspiring ! :-)

[senaranya]

It definitely is! Thank you so much for sharing!