Initial commit

application/Espo/Core/FileStorage/Attachment.php

@@ -0,0 +1,38 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage;
+
+interface Attachment
+{
+    /**
+     * Get a source ID.
+     */
+    public function getSourceId(): string;
+}

application/Espo/Core/FileStorage/AttachmentEntityWrapper.php

@@ -0,0 +1,59 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage;
+
+use Espo\Entities\Attachment as AttachmentEntity;
+
+use RuntimeException;
+
+class AttachmentEntityWrapper implements Attachment
+{
+    private AttachmentEntity $attachment;
+
+    public function __construct(AttachmentEntity $attachment)
+    {
+        if (!$attachment->getSourceId()) {
+            throw new RuntimeException("Attachment w/o a source ID.");
+        }
+
+        $this->attachment = $attachment;
+    }
+
+    public function getSourceId(): string
+    {
+        $sourceId = $this->attachment->getSourceId();
+
+        if (!$sourceId) {
+            throw new RuntimeException("Attachment w/o a source ID.");
+        }
+
+        return $sourceId;
+    }
+}

application/Espo/Core/FileStorage/Factory.php

@@ -0,0 +1,55 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage;
+
+use Espo\Core\InjectableFactory;
+use Espo\Core\Utils\Metadata;
+
+use RuntimeException;
+
+class Factory
+{
+    public function __construct(
+        private Metadata $metadata,
+        private InjectableFactory $injectableFactory
+    ) {}
+
+    public function create(string $name): Storage
+    {
+        /** @var ?class-string<Storage> $className */
+        $className = $this->metadata->get(['app', 'fileStorage', 'implementationClassNameMap', $name]);
+
+        if (!$className) {
+            throw new RuntimeException("Unknown file storage '$name'.");
+        }
+
+        return $this->injectableFactory->create($className);
+    }
+}

application/Espo/Core/FileStorage/Local.php

@@ -0,0 +1,41 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage;
+
+/**
+ * Files are stored locally.
+ */
+interface Local
+{
+    /**
+     * Get a local file path.
+     */
+    public function getLocalFilePath(Attachment $attachment): string;
+}

application/Espo/Core/FileStorage/Manager.php

@@ -0,0 +1,196 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage;
+
+use Espo\Entities\Attachment as AttachmentEntity;
+use Psr\Http\Message\StreamInterface;
+
+use GuzzleHttp\Psr7\Utils;
+
+use RuntimeException;
+
+
+/**
+ * An access point for file storing and fetching. Files are represented as Attachment entities.
+ */
+class Manager
+{
+    private const DEFAULT_STORAGE = 'EspoUploadDir';
+
+    /** @var array<string, Storage> */
+    private array $implHash = [];
+
+    /**
+     * @var array<string, resource>
+     * @noinspection PhpPropertyOnlyWrittenInspection
+     * @phpstan-ignore-next-line Used to prevent deleting from memory.
+     */
+    private $resourceMap = [];
+
+    public function __construct(private Factory $factory)
+    {}
+
+    /**
+     * Whether a file exists in a storage.
+     */
+    public function exists(AttachmentEntity $attachment): bool
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        return $implementation->exists(self::wrapAttachmentEntity($attachment));
+    }
+
+    /**
+     * Get a file size.
+     */
+    public function getSize(AttachmentEntity $attachment): int
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        return $implementation->getSize(self::wrapAttachmentEntity($attachment));
+    }
+
+    /**
+     * Get file contents.
+     */
+    public function getContents(AttachmentEntity $attachment): string
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        return $implementation->getStream(self::wrapAttachmentEntity($attachment))->getContents();
+    }
+
+    /**
+     * Get a file contents stream.
+     */
+    public function getStream(AttachmentEntity $attachment): StreamInterface
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        return $implementation->getStream(self::wrapAttachmentEntity($attachment));
+    }
+
+    /**
+     * Store file contents represented as a stream.
+     */
+    public function putStream(AttachmentEntity $attachment, StreamInterface $stream): void
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        $implementation->putStream(self::wrapAttachmentEntity($attachment), $stream);
+    }
+
+    /**
+     * Store file contents.
+     */
+    public function putContents(AttachmentEntity $attachment, string $contents): void
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        $stream = Utils::streamFor($contents);
+
+        $implementation->putStream(self::wrapAttachmentEntity($attachment), $stream);
+    }
+
+    /**
+     * Remove a file.
+     */
+    public function unlink(AttachmentEntity $attachment): void
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        $implementation->unlink(self::wrapAttachmentEntity($attachment));
+    }
+
+    /**
+     * Whether an attachment storage is local.
+     */
+    public function isLocal(AttachmentEntity $attachment): bool
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        return $implementation instanceof Local;
+    }
+
+    /**
+     * Get a local file path. If a file is not stored locally, a temporary file will be created.
+     */
+    public function getLocalFilePath(AttachmentEntity $attachment): string
+    {
+        $implementation = $this->getImplementation($attachment);
+
+        if ($implementation instanceof Local) {
+            return $implementation->getLocalFilePath(self::wrapAttachmentEntity($attachment));
+        }
+
+        $contents = $this->getContents($attachment);
+
+        $resource = tmpfile();
+
+        if ($resource === false) {
+            throw new RuntimeException("Could not create temp file.");
+        }
+
+        fwrite($resource, $contents);
+
+        // PhpStan's bug. Check later, remove 'ignore' if fixed.
+        /** @phpstan-ignore-next-line */
+        $path = stream_get_meta_data($resource)['uri'];
+
+        if (!$path) {
+            throw new RuntimeException("No uri.");
+        }
+
+        // To prevent deleting.
+        $this->resourceMap[$path] = $resource;
+
+        return $path;
+    }
+
+    private static function wrapAttachmentEntity(AttachmentEntity $attachment): AttachmentEntityWrapper
+    {
+        return new AttachmentEntityWrapper($attachment);
+    }
+
+    private function getImplementation(AttachmentEntity $attachment): Storage
+    {
+        $storage = $attachment->getStorage();
+
+        if (!$storage) {
+            $storage = self::DEFAULT_STORAGE;
+        }
+
+        if (!array_key_exists($storage, $this->implHash)) {
+            $this->implHash[$storage] = $this->factory->create($storage);
+        }
+
+        return $this->implHash[$storage];
+    }
+}

application/Espo/Core/FileStorage/Storage.php

@@ -0,0 +1,63 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage;
+
+use Psr\Http\Message\StreamInterface;
+
+/**
+ * File storing and fetching.
+ */
+interface Storage
+{
+    /**
+     * Get file contents as a stream.
+     */
+    public function getStream(Attachment $attachment): StreamInterface;
+
+    /**
+     * Store file contents.
+     */
+    public function putStream(Attachment $attachment, StreamInterface $stream): void;
+
+    /**
+     * Whether a file exists.
+     */
+    public function exists(Attachment $attachment): bool;
+
+    /**
+     * Delete a file.
+     */
+    public function unlink(Attachment $attachment): void;
+
+    /**
+     * Get a file size.
+     */
+    public function getSize(Attachment $attachment): int;
+}

application/Espo/Core/FileStorage/Storages/AwsS3.php

@@ -0,0 +1,157 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage\Storages;
+
+use Psr\Http\Message\StreamInterface;
+use AsyncAws\S3\S3Client;
+use League\Flysystem\FilesystemException;
+use League\Flysystem\AsyncAwsS3\AsyncAwsS3Adapter;
+use League\Flysystem\Filesystem;
+use GuzzleHttp\Psr7\Stream;
+
+use Espo\Core\FileStorage\Attachment;
+use Espo\Core\FileStorage\Storage;
+use Espo\Core\Utils\Config;
+
+use RuntimeException;
+
+/**
+ * @noinspection PhpUnused
+ */
+class AwsS3 implements Storage
+{
+    private Filesystem $filesystem;
+
+    public function __construct(Config $config)
+    {
+        $bucketName = $config->get('awsS3Storage.bucketName') ?? null;
+        $path = $config->get('awsS3Storage.path') ?? null;
+        $region = $config->get('awsS3Storage.region') ?? null;
+        $credentials = $config->get('awsS3Storage.credentials') ?? null;
+        $endpoint = $config->get('awsS3Storage.endpoint') ?? null;
+        $pathStyleEndpoint = $config->get('awsS3Storage.pathStyleEndpoint') ?? false;
+        $sendChunkedBody = $config->get('awsS3Storage.sendChunkedBody') ?? null;
+
+        if (!$bucketName) {
+            throw new RuntimeException("AWS S3 bucket name is not specified in config.");
+        }
+
+        /** @var array<\AsyncAws\Core\Configuration::OPTION_*, string|null> $clientOptions */
+        $clientOptions = [
+            'region' => $region,
+        ];
+
+        if ($endpoint) {
+            $clientOptions['endpoint'] = $endpoint;
+        }
+
+        if ($pathStyleEndpoint) {
+            $clientOptions['pathStyleEndpoint'] = (bool) $pathStyleEndpoint;
+        }
+
+        // Defaulted to true in the library, but the docs is not clear enough.
+        if ($sendChunkedBody !== null) {
+            $clientOptions['sendChunkedBody'] = (bool) $sendChunkedBody;
+        }
+
+        if ($credentials && is_array($credentials)) {
+            $clientOptions['accessKeyId'] = $credentials['key'] ?? null;
+            $clientOptions['accessKeySecret'] = $credentials['secret'] ?? null;
+        }
+
+        $client = new S3Client($clientOptions);
+        $adapter = new AsyncAwsS3Adapter($client, $bucketName, $path);
+
+        $this->filesystem = new Filesystem($adapter);
+    }
+
+    public function unlink(Attachment $attachment): void
+    {
+        try {
+            $this->filesystem->delete($attachment->getSourceId());
+        } catch (FilesystemException $e) {
+            throw new RuntimeException($e->getMessage(), 0, $e);
+        }
+    }
+
+    public function exists(Attachment $attachment): bool
+    {
+        try {
+            return $this->filesystem->fileExists($attachment->getSourceId());
+        } catch (FilesystemException $e) {
+            throw new RuntimeException($e->getMessage(), 0, $e);
+        }
+    }
+
+    public function getSize(Attachment $attachment): int
+    {
+        try {
+            return $this->filesystem->fileSize($attachment->getSourceId());
+        } catch (FilesystemException $e) {
+            throw new RuntimeException($e->getMessage(), 0, $e);
+        }
+    }
+
+    public function getStream(Attachment $attachment): StreamInterface
+    {
+        try {
+            $resource = $this->filesystem->readStream($attachment->getSourceId());
+        } catch (FilesystemException $e) {
+            throw new RuntimeException($e->getMessage(), 0, $e);
+        }
+
+        return new Stream($resource);
+    }
+
+    public function putStream(Attachment $attachment, StreamInterface $stream): void
+    {
+        // League\Flysystem does not support StreamInterface.
+        // Need to pass a resource.
+
+        $resource = fopen('php://temp', 'r+');
+
+        if ($resource === false) {
+            throw new RuntimeException("Could not open temp.");
+        }
+
+        $stream->rewind();
+
+        fwrite($resource, $stream->getContents());
+        rewind($resource);
+
+        try {
+            $this->filesystem->writeStream($attachment->getSourceId(), $resource);
+        } catch (FilesystemException $e) {
+            throw new RuntimeException($e->getMessage(), 0, $e);
+        }
+
+        fclose($resource);
+    }
+}

application/Espo/Core/FileStorage/Storages/EspoUploadDir.php

@@ -0,0 +1,121 @@
+<?php
+/************************************************************************
+ * This file is part of EspoCRM.
+ *
+ * EspoCRM – Open Source CRM application.
+ * Copyright (C) 2014-2025 EspoCRM, Inc.
+ * Website: https://www.espocrm.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ *
+ * The interactive user interfaces in modified source and object code versions
+ * of this program must display Appropriate Legal Notices, as required under
+ * Section 5 of the GNU Affero General Public License version 3.
+ *
+ * In accordance with Section 7(b) of the GNU Affero General Public License version 3,
+ * these Appropriate Legal Notices must retain the display of the "EspoCRM" word.
+ ************************************************************************/
+
+namespace Espo\Core\FileStorage\Storages;
+
+use Espo\Core\FileStorage\Attachment;
+use Espo\Core\FileStorage\Local;
+use Espo\Core\FileStorage\Storage;
+use Espo\Core\Utils\File\Manager as FileManager;
+use Espo\Core\Utils\File\Exceptions\FileError;
+
+use Psr\Http\Message\StreamInterface;
+use GuzzleHttp\Psr7\Stream;
+
+class EspoUploadDir implements Storage, Local
+{
+
+    public const NAME = 'EspoUploadDir';
+
+    public function __construct(protected FileManager $fileManager)
+    {}
+
+    public function unlink(Attachment $attachment): void
+    {
+        $this->fileManager->unlink(
+            $this->getFilePath($attachment)
+        );
+    }
+
+    public function exists(Attachment $attachment): bool
+    {
+        $filePath = $this->getFilePath($attachment);
+
+        return $this->fileManager->isFile($filePath);
+    }
+
+    public function getSize(Attachment $attachment): int
+    {
+        $filePath = $this->getFilePath($attachment);
+
+        if (!$this->exists($attachment)) {
+            throw new FileError("Could not get size for non-existing file '$filePath'.");
+        }
+
+        return $this->fileManager->getSize($filePath);
+    }
+
+    public function getStream(Attachment $attachment): StreamInterface
+    {
+        $filePath = $this->getFilePath($attachment);
+
+        if (!$this->exists($attachment)) {
+            throw new FileError("Could not get stream for non-existing '$filePath'.");
+        }
+
+        $resource = fopen($filePath, 'r');
+
+        if ($resource === false) {
+            throw new FileError("Could not open '$filePath'.");
+        }
+
+        return new Stream($resource);
+    }
+
+    public function putStream(Attachment $attachment, StreamInterface $stream): void
+    {
+        $filePath = $this->getFilePath($attachment);
+
+        $stream->rewind();
+
+        // @todo Use a resource to write a file (add a method to the file manager).
+        $contents = $stream->getContents();
+
+        $result = $this->fileManager->putContents($filePath, $contents);
+
+        if (!$result) {
+            throw new FileError("Could not store a file '$filePath'.");
+        }
+    }
+
+    public function getLocalFilePath(Attachment $attachment): string
+    {
+        return $this->getFilePath($attachment);
+    }
+
+    /**
+     * @return string
+     */
+    protected function getFilePath(Attachment $attachment)
+    {
+        $sourceId = $attachment->getSourceId();
+
+        return 'data/upload/' . $sourceId;
+    }
+}