diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a3fb84..fd3de3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,11 @@ # (MODX)EvolutionCMS.libraries.ddInstaller changelog +## Version 0.3 (2024-12-04) + +* \+ `\DDInstaller::install($params)` → Parameters → `$params->revision`: The new optional parameter. Allows to specify the branch name, tag name, or commit hash to retrieve. + + ## Version 0.2 (2024-09-13) * \+ `\DDInstaller::install($params)` → Parameters → `$params->type`: The parameter has become optional. The method will detect type automatically from `$params->url` (see README). diff --git a/CHANGELOG_ru.md b/CHANGELOG_ru.md index 2fcb44c..dad97c0 100644 --- a/CHANGELOG_ru.md +++ b/CHANGELOG_ru.md @@ -1,6 +1,11 @@ # (MODX)EvolutionCMS.libraries.ddInstaller changelog +## Версия 0.3 (2024-12-04) + +* \+ `\DDInstaller::install($params)` → Параметры → `$params->revision`: Новый необязательный параметр. Позволяет задать имя ветки, тега или хэш кэммита для получения. + + ## Версия 0.2 (2024-09-13) * \+ `\DDInstaller::install($params)` → Параметры → `$params->type`: Параметр стал необязательным. Метод определит тип автоматически из `$params->url` (см. README). diff --git a/EvolutionCMS.libraries.ddInstaller.php b/EvolutionCMS.libraries.ddInstaller.php index 3a7668d..118f188 100644 --- a/EvolutionCMS.libraries.ddInstaller.php +++ b/EvolutionCMS.libraries.ddInstaller.php @@ -1,7 +1,7 @@ url {stringUrl} — Resource GitHub URL (e. g. `https://github.com/DivanDesign/EvolutionCMS.libraries.ddTools`). @required + * @param [$params->revision='master'] {string} — The branch name, tag name, or commit hash to retrieve. * @param [$params->type] {'Snippet'|'Plugin'|'Library'} — Resource type. * * @return {boolean} @@ -54,7 +55,7 @@ public static function install($params){ ], ]); - return $installerObject->install(); + return $installerObject->install($params->revision ?? null); } } ?> \ No newline at end of file diff --git a/README.md b/README.md index 2f5f14e..fa36c41 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,12 @@ Installs or updates needed snippet, plugin, or library. * Valid values: `stringUrl` * **Required** +* `$params->revision` + * Description: The branch name, tag name, or commit hash to retrieve. + * If you specify anything other than `'master'` or any version tag, the distributive will be installed regardless of the `composer.json` version. This is useful for installing developer versions. + * Valid values: `string` + * Default value: `'master'` + * `$params->type` * Description: Resource type. * The parameter is case insensitive. diff --git a/README_ru.md b/README_ru.md index 8018f89..d3ffdaa 100644 --- a/README_ru.md +++ b/README_ru.md @@ -73,6 +73,12 @@ * Допустимые значения: `stringUrl` * **Обязателен** +* `$params->revision` + * Описание: Имя ветки, тега или хэш кэммита для получения. + * Если задать что-то кроме `'master'` или какого-либо тега версии, дистрибутив будет установлен независимо от версии `composer.json`. Это удобно для установки девелоперских версий. + * Допустимые значения: `string` + * Значение по умолчанию: `'master'` + * `$params->type` * Описание: Тип ресурса. * Параметр не чувствителен к регистру. diff --git a/composer.json b/composer.json index 158bd83..e37fe17 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "dd/evolutioncms-libraries-ddinstaller", "type": "modxevo-library", - "version": "0.2.0", + "version": "0.3.0", "description": "The library for install and update snippets, plugins and libraries.", "keywords": [ "modx", diff --git a/src/Installer/Installer.php b/src/Installer/Installer.php index 4616fa3..b0aa587 100644 --- a/src/Installer/Installer.php +++ b/src/Installer/Installer.php @@ -4,45 +4,43 @@ abstract class Installer extends \DDTools\Base\Base { use \DDTools\Base\AncestorTrait; - protected - /** - * @property $distrData {stdClass} - * @property $distrData->fullName {string} — Resource full name (e. g. `EvolutionCMS.libraries.ddTools`). - * @property $distrData->shortName {string} — Resource short name (e. g. `ddTools`). - * @property $distrData->type {'library'|'snippet'|'plugin'} — Resource type. - * @property $distrData->owner {string} — Resource GitHub owner (e. g. `DivanDesign`). - */ - $distrData = [ - 'fullName' => '', - 'shortName' => '', - 'type' => '', - 'owner' => '', - ], - - /** - * @property $paths {stdClass} - * @property $paths->assetsDir {string} — Full path of `assets` (e. g. `/var/www/someuser/data/www/somesite.com/assets/`). - * @property $paths->destinationDir {string} — Resource destination full path (e. g. `/var/www/someuser/data/www/somesite.com/assets/libs/ddTools/`). - * @property $paths->cacheDir {string} — Full path of `assets/cache/ddInstaller` (e. g. `/var/www/someuser/data/www/somesite.com/assets/cache/ddInstaller/`). - * @property $paths->cacheFile {string} — Full path name of cache file (e. g. `/var/www/someuser/data/www/somesite.com/assets/cache/ddInstaller/EvolutionCMS.libraries.ddTools.zip`). - */ - $paths = [ - 'assetsDir' => '', - 'destinationDir' => '', - 'cacheDir' => '', - 'cacheFile' => '', - ], - - /** - * @property $dbSettings {stdClass} - * @property $dbSettings->tableName {string} - * @property $dbSettings->contentField {string} - */ - $dbSettings = [ - 'tableName' => null, - 'contentField' => null, - ] - ; + /** + * @property $distrData {stdClass} + * @property $distrData->fullName {string} — Resource full name (e. g. `EvolutionCMS.libraries.ddTools`). + * @property $distrData->shortName {string} — Resource short name (e. g. `ddTools`). + * @property $distrData->type {'library'|'snippet'|'plugin'} — Resource type. + * @property $distrData->owner {string} — Resource GitHub owner (e. g. `DivanDesign`). + */ + protected $distrData = [ + 'fullName' => '', + 'shortName' => '', + 'type' => '', + 'owner' => '', + ]; + + /** + * @property $paths {stdClass} + * @property $paths->assetsDir {string} — Full path of `assets` (e. g. `/var/www/someuser/data/www/somesite.com/assets/`). + * @property $paths->destinationDir {string} — Resource destination full path (e. g. `/var/www/someuser/data/www/somesite.com/assets/libs/ddTools/`). + * @property $paths->cacheDir {string} — Full path of `assets/cache/ddInstaller` (e. g. `/var/www/someuser/data/www/somesite.com/assets/cache/ddInstaller/`). + * @property $paths->cacheFile {string} — Full path name of cache file (e. g. `/var/www/someuser/data/www/somesite.com/assets/cache/ddInstaller/EvolutionCMS.libraries.ddTools.zip`). + */ + protected $paths = [ + 'assetsDir' => '', + 'destinationDir' => '', + 'cacheDir' => '', + 'cacheFile' => '', + ]; + + /** + * @property $dbSettings {stdClass} + * @property $dbSettings->tableName {string} + * @property $dbSettings->contentField {string} + */ + protected $dbSettings = [ + 'tableName' => null, + 'contentField' => null, + ]; /** * __construct @@ -182,14 +180,20 @@ protected function fillPaths_destination(){ /** * install - * @version 1.0.2 (2024-09-13) + * @version 1.1 (2024-12-03) + * + * @param [$revision='master'] {string} — The branch name, tag name, or commit hash to retrieve. * * @return {boolean} — Is resource installed? */ - public function install(){ + public function install(?string $revision = null){ $result = false; - if ($this->downloadDistrZip()){ + if (empty($revision)){ + $revision = 'master'; + } + + if ($this->downloadDistrZip($revision)){ $distrZipObject = new \ZipArchive; $distrZipObject->open($this->paths->cacheFile); @@ -210,7 +214,12 @@ public function install(){ ]); } - if ($this->isNeedToInstall($distrComposerJson)){ + if ( + $this->isNeedToInstall([ + 'distrComposerJson' => $distrComposerJson, + 'distrRevision' => $revision, + ]) + ){ // Just remove exist dir \DDTools\FilesTools::removeDir($this->paths->destinationDir); // And create again @@ -304,11 +313,13 @@ public function install(){ /** * downloadDistrZip - * @version 1.0.2 (2024-09-13) + * @version 2.0 (2024-12-03) + * + * @param $revision {string} — The branch name, tag name, or commit hash to retrieve. * * @return {boolean} */ - protected function downloadDistrZip(){ + protected function downloadDistrZip($revision){ $result = false; $fileContent = \DDTools\Snippet::runSnippet([ @@ -320,6 +331,7 @@ protected function downloadDistrZip(){ . '/' . $this->distrData->fullName . '/zipball/' + . $revision , 'userAgent' => \ddTools::$modx->getConfig('site_url'), 'headers' => [ @@ -350,22 +362,26 @@ protected function downloadDistrZip(){ } /** - * isInstallNeeded - * @version 1.0.2 (2024-09-13) + * isNeedToInstall + * @version 2.0 (2024-09-13) * - * @param $distrComposerJson {stdClass} + * @param $params {stdClass|arrayAssociative} — The parameters object. + * @param $params->distrComposerJson {stdClass} + * @param $params->distrRevision {string} * * @return {boolean} */ - protected function isNeedToInstall($distrComposerJson){ + protected function isNeedToInstall($params){ + $params = (object) $params; + // Don't want to install by default $result = false; if ( // We don't do anything if the repository has no `composer.json` - is_object($distrComposerJson) + is_object($params->distrComposerJson) // Version is required - && !empty($distrComposerJson->version) + && !empty($params->distrComposerJson->version) ){ $existComposerJson = $this->paths->destinationDir @@ -389,9 +405,19 @@ protected function isNeedToInstall($distrComposerJson){ if ( // If destination version is absent empty($existComposerJson->version) + // If it is not `master` or some version tag — install independen of composer version + || ( + $params->distrRevision != 'master' + && substr( + $params->distrRevision, + 0, + 1 + ) + !== 'v' + ) // Or distr version > destination version || version_compare( - $distrComposerJson->version, + $params->distrComposerJson->version, $existComposerJson->version, '>' ) diff --git a/src/Installer/Library/Installer.php b/src/Installer/Library/Installer.php index 40ab364..f33bab3 100644 --- a/src/Installer/Library/Installer.php +++ b/src/Installer/Library/Installer.php @@ -5,7 +5,7 @@ class Installer extends \DDInstaller\Installer\Installer { /** * fillPaths_destination * @version 1.0.1 (2024-09-13) - * + * * @return {void} */ protected final function fillPaths_destination(){ diff --git a/src/Installer/Plugin/Installer.php b/src/Installer/Plugin/Installer.php index 13a7a91..b04f3cc 100644 --- a/src/Installer/Plugin/Installer.php +++ b/src/Installer/Plugin/Installer.php @@ -2,16 +2,14 @@ namespace DDInstaller\Installer\Plugin; class Installer extends \DDInstaller\Installer\Installer { - protected - /** - * @property $dbSettings {stdClass} - * @property $dbSettings->tableName {string} - * @property $dbSettings->contentField {string} - */ - $dbSettings = [ - 'tableName' => 'site_plugins', - 'contentField' => 'plugincode', - ] - ; + /** + * @property $dbSettings {stdClass} + * @property $dbSettings->tableName {string} + * @property $dbSettings->contentField {string} + */ + protected $dbSettings = [ + 'tableName' => 'site_plugins', + 'contentField' => 'plugincode', + ]; } ?> \ No newline at end of file diff --git a/src/Installer/Snippet/Installer.php b/src/Installer/Snippet/Installer.php index f1c6057..099a19c 100644 --- a/src/Installer/Snippet/Installer.php +++ b/src/Installer/Snippet/Installer.php @@ -2,16 +2,15 @@ namespace DDInstaller\Installer\Snippet; class Installer extends \DDInstaller\Installer\Installer { - protected - /** - * @property $dbSettings {stdClass} - * @property $dbSettings->tableName {string} - * @property $dbSettings->contentField {string} - */ - $dbSettings = [ - 'tableName' => 'site_snippets', - 'contentField' => 'snippet', - ] - ; + + /** + * @property $dbSettings {stdClass} + * @property $dbSettings->tableName {string} + * @property $dbSettings->contentField {string} + */ + protected $dbSettings = [ + 'tableName' => 'site_snippets', + 'contentField' => 'snippet', + ]; } ?> \ No newline at end of file