class.ilDataSet.php

Go to the documentation of this file.

<?php

use ILIAS\ResourceStorage\Collection\ResourceCollection;
use ILIAS\ResourceStorage\Resource\StorableContainerResource;
use ILIAS\ResourceStorage\Identification\ResourceIdentification;
use ILIAS\ResourceStorage\Resource\StorableResource;
use ILIAS\Dataset\IRSSContainerExportConfig;

abstract class ilDataSet
{
    public const DATASET_NS = 'http://www.ilias.de/Services/DataSet/ds/4_3';
    public const DATASET_NS_PREFIX = 'ds';

    public const EXPORT_NO_INST_ID = 1;
    public const EXPORT_ID_ILIAS_LOCAL = 2;
    public const EXPORT_ID_ILIAS_LOCAL_INVALID = 3;
    public const EXPORT_ID_ILIAS_REMOTE = 4;
    public const EXPORT_ID_ILIAS_REMOTE_INVALID = 5;
    public const EXPORT_ID = 6;
    public const EXPORT_ID_INVALID = 7;
    protected \ILIAS\ResourceStorage\Services $irss;

    public int $dircnt = 0;
    protected string $current_installation_id = "";
    protected array $data = [];
    protected ilDBInterface $db;
    protected ilLogger $ds_log;
    protected string $import_directory = "";
    protected string $entity = "";
    protected string $schema_version = "";
    protected string $component_export_dir = "";
    protected string $ds_prefix = "ds";
    protected string $version = "";
    protected ilSurveyImporter $import;
    protected ilExport $export;

    public function __construct()
    {
        global $DIC;

        $this->db = $DIC->database();
        $this->ds_log = ilLoggerFactory::getLogger('ds');
        $this->irss = $DIC->resourceStorage();
    }

    final public function init(string $a_entity, string $a_schema_version): void
    {
        $this->entity = $a_entity;
        $this->schema_version = $a_schema_version;
        $this->data = array();
    }

    abstract public function getSupportedVersions(): array;

    abstract protected function getTypes(string $a_entity, string $a_version): array;

    abstract protected function getXmlNamespace(string $a_entity, string $a_schema_version): string;

    abstract public function readData(
        string $a_entity,
        string $a_version,
        array $a_ids
    ): void;

    public function initByExporter(ilXmlExporter $xml_exporter): void
    {
        $this->export = $xml_exporter->getExport();
    }

    public function setImportDirectory(string $a_val): void
    {
        $this->import_directory = $a_val;
    }

    public function getImportDirectory(): string
    {
        return $this->import_directory;
    }

    public function setDSPrefix(string $a_val): void
    {
        $this->ds_prefix = $a_val;
    }

    public function getDSPrefix(): string
    {
        return $this->ds_prefix;
    }

    public function getDSPrefixString(): string
    {
        if ($this->getDSPrefix() !== "") {
            return $this->getDSPrefix() . ":";
        }
        return "";
    }

    public function getDirectDataFromQuery(
        string $a_query,
        bool $a_convert_to_leading_upper = true,
        bool $a_set = true
    ): array {
        $ilDB = $this->db;

        $set = $ilDB->query($a_query);
        $this->data = array();
        $ret = [];
        while ($rec = $ilDB->fetchAssoc($set)) {
            if ($a_convert_to_leading_upper) {
                $tmp = array();
                foreach ($rec as $k => $v) {
                    $tmp[$this->convertToLeadingUpper($k)]
                        = $v;
                }
                $rec = $tmp;
            }

            if ($a_set) {
                $this->data[] = $rec;
            }
            $ret[] = $rec;
        }
        return $ret;
    }

    public function convertToLeadingUpper(string $a_str): string
    {
        $a_str = strtoupper(substr($a_str, 0, 1)) . substr($a_str, 1);
        while (($pos = strpos($a_str, "_")) !== false) {
            $a_str = substr($a_str, 0, $pos) .
                strtoupper(substr($a_str, $pos + 1, 1)) .
                substr($a_str, $pos + 2);
        }
        return $a_str;
    }


    final public function getXmlRepresentation(
        string $a_entity,
        string $a_schema_version,
        ?array $a_ids,
        string $a_field = "",
        bool $a_omit_header = false,
        bool $a_omit_types = false
    ): string {
        $this->dircnt = 1;

        // init writer
        $writer = new ilXmlWriter();
        if (!$a_omit_header) {
            $writer->xmlHeader();
        }

        // collect namespaces
        $namespaces = $prefixes = array();
        $this->getNamespaces($namespaces, $a_entity, $a_schema_version);
        $atts = array("InstallationId" => IL_INST_ID,
            "InstallationUrl" => ILIAS_HTTP_PATH, "TopEntity" => $a_entity);
        $cnt = 1;
        foreach ($namespaces as $entity => $ns) {
            $prefix = "ns" . $cnt;
            $prefixes[$entity] = $prefix;
            //                  $atts["xmlns:".$prefix] = $ns;
            $cnt++;
        }
        $this->ds_log->debug("Start writing Dataset, entity: " . $a_entity . ", schema version: " . $a_schema_version .
            ", ids: " . print_r($a_ids, true));

        if ($this->getDSPrefix() !== '') {
            $atts['xmlns:' . $this->getDSPrefix()] = self::DATASET_NS;
        } else {
            $atts['xmlns'] = self::DATASET_NS;
        }
        $writer->xmlStartTag($this->getDSPrefixString() . 'DataSet', $atts);
        // add types
        if (!$a_omit_types) {
            $this->ds_log->debug("...write types");
            $this->addTypesXml($writer, $a_entity, $a_schema_version);
        }
        // add records
        $this->ds_log->debug("...write records");
        $this->addRecordsXml($writer, $prefixes, $a_entity, $a_schema_version, $a_ids, $a_field);

        $writer->xmlEndTag($this->getDSPrefixString() . "DataSet");

        return $writer->xmlDumpMem(false);
    }

    protected function getExportDirInContainer(string $exp_dir): string
    {
        // note, the export returns in ILIAS 10 (Jan 2024) something like
        // 1737382047__0__cat_436/components/ILIAS/Style/set_0/dsDir_1
        // whereas ILIAS 9 returned
        // Services/Style/set_1/expDir_1/dsDir_1
        // thus we skip the 1737382047__0__cat_436/ part since it would be redundant
        // an make import fail
        if (str_contains($exp_dir, "components/")) {
            $exp_dir = substr($exp_dir, strpos($exp_dir, "components/"));
        }
        return $exp_dir;
    }

    public function addRecordsXml(
        ilXmlWriter $a_writer,
        array $a_prefixes,
        string $a_entity,
        string $a_schema_version,
        array $a_ids,
        ?string $a_field = ""
    ): void {
        $types = $this->getXmlTypes($a_entity, $a_schema_version);
        $this->ds_log->debug("...read data");
        $this->readData($a_entity, $a_schema_version, $a_ids);
        $this->ds_log->debug("...data: " . print_r($this->data, true));
        foreach ($this->data as $d) {
            $a_writer->xmlStartTag(
                $this->getDSPrefixString() . "Rec",
                array("Entity" => $this->getXMLEntityName($a_entity, $a_schema_version))
            );
            $a_writer->xmlStartTag($this->getXMLEntityTag($a_entity, ''));
            $rec = $this->getXmlRecord($a_entity, $a_schema_version, $d);
            foreach ($rec as $f => $c) {
                if (isset($this->export) and ($types[$f] ?? "") === "directory") {
                    $sdir = realpath($c);
                    $path_in_container = $this->export->getPathToComponentExpDirInContainer() . "/dsDir_" . $this->dircnt;
                    $this->export->getExportWriter()->writeDirectory(
                        $sdir,
                        $path_in_container
                    );
                    $c = $this->getExportDirInContainer($path_in_container);  // note: this corrects the path, see above
                    $this->dircnt++;
                }
                if (isset($this->export) and ($types[$f] ?? "") === "rscollection") {
                    $path_in_container = $this->export->getPathToComponentExpDirInContainer() . "/dsDir_" . $this->dircnt;
                    $collection = $this->getCollection($rec, $a_entity, $a_schema_version, $f, $c);
                    if (!is_null($collection)) {
                        $this->export->getExportWriter()->writeFilesByResourceCollection(
                            $collection,
                            $path_in_container
                        );
                    }

                    $c = $this->getExportDirInContainer($path_in_container);  // note: this corrects the path, see above
                    $this->dircnt++;
                }
                if (isset($this->export) and ($types[$f] ?? "") === "rscontainer") {
                    $path_in_container = "/dsDir_" . $this->dircnt;
                    if ($this->export->isContainerExport()) { // note: this checks if the export is in a container context and adds the set number to the path accordingly
                        $path_in_container = $this->export->getPathToComponentExpDirInContainerWithLeadingSetNumber() . $path_in_container;
                    } else {
                        $path_in_container = $this->export->getPathToComponentExpDirInContainer() . $path_in_container;
                    }
                    if ($config = $this->getContainerExportConfig($rec, $a_entity, $a_schema_version, $f, $c)) {
                        $this->export->getExportWriter()->writeFilesByResourceContainer(
                            $this->getIRSSContainerExportConfig(
                                $config->getSourceContainer(),
                                $config->getSourcePath(),
                                $path_in_container
                            )
                        );
                    }
                    $c = $this->getExportDirInContainer($path_in_container);  // note: this corrects the path, see above
                    $this->dircnt++;
                }
                // this changes schema/dtd
                //$a_writer->xmlElement($a_prefixes[$a_entity].":".$f,
                //      array(), $c);
                $a_writer->xmlElement($f, array(), $c);
            }

            $a_writer->xmlEndTag($this->getXMLEntityTag($a_entity, ''));

            $a_writer->xmlEndTag($this->getDSPrefixString() . "Rec");

            $this->afterXmlRecordWriting($a_entity, $a_schema_version, $d);

            // foreach record records of dependent entities
            $this->ds_log->debug("...get dependencies");
            $deps = $this->getDependencies($a_entity, $a_schema_version, $rec, $a_ids);
            $this->ds_log->debug("...dependencies: " . print_r($deps, true));
            foreach ($deps as $dp => $par) {
                $ids = !is_array($par["ids"])
                    ? [$par["ids"]]
                    : $par["ids"];
                $this->addRecordsXml($a_writer, $a_prefixes, $dp, $a_schema_version, $ids, $par["field"] ?? null);
            }
        }
    }

    protected function getIRSSContainerExportConfig(
        StorableResource $source_container,
        string $source_path,
        string $target_path = ""
    ): IRSSContainerExportConfig {
        return new IRSSContainerExportConfig(
            $source_container,
            $source_path,
            $target_path
        );
    }

    protected function getDependencies(
        string $a_entity,
        string $a_version,
        ?array $a_rec = null,
        ?array $a_ids = null
    ): array {
        return [];
    }

    // After xml record writing hook record
    public function afterXmlRecordWriting(string $a_entity, string $a_version, array $a_set): void
    {
    }

    // Add types to xml writer
    private function addTypesXml(ilXmlWriter $a_writer, string $a_entity, string $a_schema_version): void
    {
        $types = $this->getXmlTypes($a_entity, $a_schema_version);

        // add types of current entity
        if (count($types) > 0) {
            $a_writer->xmlStartTag(
                $this->getDSPrefixString() . "Types",
                array("Entity" => $this->getXMLEntityName($a_entity, $a_schema_version),
                    "SchemaVersion" => $a_schema_version)
            );
            foreach ($this->getXmlTypes($a_entity, $a_schema_version) as $f => $t) {
                $a_writer->xmlElement(
                    $this->getDSPrefixString() . 'FieldType',
                    array("Name" => $f, "Type" => $t)
                );
            }
            $a_writer->xmlEndTag($this->getDSPrefixString() . "Types");
        }

        // add types of dependent entities
        $deps = $this->getDependencies($a_entity, $a_schema_version, null, null);
        foreach ($deps as $dp => $w) {
            $this->addTypesXml($a_writer, $dp, $a_schema_version);
        }
    }

    // Get xml namespaces
    public function getNamespaces(array &$namespaces, string $a_entity, string $a_schema_version): void
    {
        $ns = $this->getXmlNamespace($a_entity, $a_schema_version);
        if ($ns !== "") {
            $namespaces[$a_entity] = $ns;
        }
        // add types of dependent entities
        $deps = $this->getDependencies($a_entity, $a_schema_version, null, null);
        foreach ($deps as $dp => $w) {
            $this->getNamespaces($namespaces, $dp, $a_schema_version);
        }
    }

    public function getXmlRecord(string $a_entity, string $a_version, array $a_set): array
    {
        return $a_set;
    }

    public function getXmlTypes(string $a_entity, string $a_version): array
    {
        return $this->getTypes($a_entity, $a_version);
    }

    public function getXMLEntityName(string $a_entity, string $a_version): string
    {
        return $a_entity;
    }

    public function getXMLEntityTag(string $a_entity, string $a_schema_version): string
    {
        return $this->convertToLeadingUpper($a_entity);
    }

    public function setImport(ilSurveyImporter $a_val): void
    {
        $this->import = $a_val;
    }

    public function getImport(): ilSurveyImporter
    {
        return $this->import;
    }

    public function setCurrentInstallationId(string $a_val): void
    {
        $this->current_installation_id = $a_val;
    }

    public function getCurrentInstallationId(): string
    {
        return $this->current_installation_id;
    }

    protected function createObjectExportId(string $a_type, string $a_id): string
    {
        return "il_" . IL_INST_ID . "_" . $a_type . "_" . $a_id;
    }

    protected function parseObjectExportId(string $a_id, ?string $a_fallback_id = null): array
    {
        // ilias export id?
        if (strpos($a_id, "il_") === 0) {
            $parts = explode("_", $a_id);
            if (count($parts) !== 4) {
                throw new ilException("Invalid import ID '" . $a_id . "'.");
            }
            $inst_id = $parts[1];
            $type = $parts[2];
            $id = $parts[3];

            // missing installation ids?
            if (($inst_id == 0 || IL_INST_ID === "0") && !DEVMODE) {
                return array("type" => self::EXPORT_NO_INST_ID, "id" => $a_fallback_id);
            }

            // same installation?
            if ($inst_id == IL_INST_ID) {
                // still existing?
                if (ilObject::_lookupType($id) === $type) {
                    return array("type" => self::EXPORT_ID_ILIAS_LOCAL, "id" => $id);
                }
                // not found
                else {
                    return array("type" => self::EXPORT_ID_ILIAS_LOCAL_INVALID, "id" => $a_fallback_id);
                }
            }
            // different installation
            else {
                $id = ilObject::_getIdForImportId($a_id);
                // matching type?
                if ($id && ilObject::_lookupType($id) === $type) {
                    return array("type" => self::EXPORT_ID_ILIAS_REMOTE, "id" => $id);
                }
                // not found
                else {
                    return array("type" => self::EXPORT_ID_ILIAS_REMOTE_INVALID, "id" => $a_fallback_id);
                }
            }
        } else {
            // external id
            $id = ilObject::_getIdForImportId($a_id);
            if ($id) {
                return array("type" => self::EXPORT_ID, "id" => $id);
            } else {
                return array("type" => self::EXPORT_ID_INVALID, "id" => $a_fallback_id);
            }
        }
    }

    public function importRecord(
        string $a_entity,
        array $a_types,
        array $a_rec,
        ilImportMapping $a_mapping,
        string $a_schema_version
    ): void {
    }

    public function getCollection(
        array $record,
        string $entity,
        string $schema_version,
        string $field,
        string $value
    ): ?ResourceCollection {
        return null;
    }

    public function getContainerExportConfig(
        array $record,
        string $entity,
        string $schema_version,
        string $field,
        string $value
    ): ?IRSSContainerExportConfig {
        return null;
    }

    protected function stripTags(array $rec, array $omit_keys = []): array
    {
        $ret_rec = [];
        foreach ($rec as $k => $v) {
            if (in_array($k, $omit_keys, true)) {
                $ret_rec[$k] = $v;
            } else {
                $ret_rec[$k] = ilUtil::stripSlashes($v);
            }
        }
        return $ret_rec;
    }
}