Version 0.3

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).

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).

EvolutionCMS.libraries.ddInstaller.php

@@ -1,7 +1,7 @@
 <?php
 /**
  * ddInstaller
- * @version 0.2 (2024-09-13)
+ * @version 0.3 (2024-12-04)
  * 
  * @see README.md
  * 
@@ -12,10 +12,11 @@
 class DDInstaller {
 	/**
 	 * install
-	 * @version 1.1 (2024-09-13)
+	 * @version 1.2 (2024-12-03)
 	 * 
 	 * @param $params {stdClass|arrayAssociative|stringJsonObject|stringHjsonObject|stringQueryFormatted} — @required
 	 * @param $params->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);
 	}
 }
 ?>

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.

README_ru.md

@@ -73,6 +73,12 @@
 	* Допустимые значения: `stringUrl`
 	* **Обязателен**
 
+* `$params->revision`
+	* Описание: Имя ветки, тега или хэш кэммита для получения.
+		* Если задать что-то кроме `'master'` или какого-либо тега версии, дистрибутив будет установлен независимо от версии `composer.json`. Это удобно для установки девелоперских версий.
+	* Допустимые значения: `string`
+	* Значение по умолчанию: `'master'`
+
 * `$params->type`
 	* Описание: Тип ресурса.
 		* Параметр не чувствителен к регистру.

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",

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,
 						'>'
 					)

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(){

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',
+	];
 }
 ?>

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',
+	];
 }
 ?>