README

The library for installing and updating snippets, plugins, and libraries from GitHub and GitLab repositories.

How it works

Terms

• “Site” — your site.
• “Resource” — snippet, plugin or library that you want to install or update.

Algorithm

1. First, the library downloads the repository archive of Resource from GitHub or GitLab using API and temporary saves it in assets/cache/ddInstaller/.
2. Then it decides whether to install / update Resource or not.
   To do this it looks at the composer.json file from the archive and compares with composer.json of Resource on your Site:
   • Resource will be installed or updated if:
     1. composer.json in the archive:
        • Is exist.
        • And not empty.
        • And contains the valid version field.
     2. composer.json on Site:
        • Is not exist.
        • Or empty.
        • Or doesn't contain the version field.
        • Or the version field is invalid.
     3. version in the archive > version on Site.
   • Otherwise, Resource will not be installed.
3. To avoid accumulation of trash files, the library removes the existing Resource folder before installation and creates it again (e. g. assets/snippets/ddGetDate/).
4. If Resource is a snippet or plugin, the library tries to find its DB file (e. g. ddGetDate_snippet.php) and installs / upates it to DB.
5. Finally, the library copies remaining files and subfolders to the Resource folder.

Requires

• PHP >= 7.4
• (MODX)EvolutionCMS >= 1.1
• (MODX)EvolutionCMS.libraries.ddTools >= 0.63
• (MODX)EvolutionCMS.snippets.ddMakeHttpRequest >= 2.4

Installation

Elements → Manage Files:

1. Create a new folder assets/libs/ddInstaller/.
2. Extract the archive to the folder.

Parameters description

\DDInstaller::install($params)

Installs or updates needed snippet, plugin, or library.

• $params

  • Description: Parameters, the pass-by-name style is used.
  • Valid values:
    • arrayAssociative
    • object
    • stringJsonObject — as JSON
    • stringHjsonObject — as HJSON
    • stringQueryFormatted — as Query string
  • Required

• $params->url

  • Description: Resource GitHub or GitLab URL.
    • Repository root URL only — without /-/tree/..., /-/blob/... and other path suffixes.
    • E. g. 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDate'
    • E. g. 'https://gitlab.com/DivanDesign/SomeGroup/EvolutionCMS.snippets.ddGetDate'
  • Valid values: stringUrl
  • Required

• $params->revision

  • Description: The branch name, tag name, or commit hash to retrieve.
    • If you specify anything other than 'master'/'main' 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.
    • If $params->url contain the following words, you can avoid this parameter and the method will detect type automatically:
      • 'snippet', 'snippets' — 'snippet'
      • 'plugin', 'plugins' — 'plugin'
      • 'library', 'libraries' — 'library'
  • Valid values:
    • 'snippet'
    • 'plugin'
    • 'library'
    • any empty value — will be auto detected from $params->url
  • Default value: —

• $params->token

  • Description: Access token for private repositories.
    • GitHub: Personal Access Token (classic: repo scope, fine-grained: Contents: Read-only).
    • GitLab: Personal Access Token with read_api scope (archive API does not accept read_repository, see gitlab#28324).
  • Valid values: string
  • Default value: —

Returns

• $result
  • Description: Installation status.
  • Valid values:
    • true — if the resource is installed or updated successfully
    • false — if something went wrong or the resource on Site is already up to date

Examples

GitHub: Install or update the ddGetDate snippet

Just run the following PHP code in your sources or Console:

// Include (MODX)EvolutionCMS.libraries.ddInstaller
require_once(
	$modx->getConfig('base_path')
	. 'assets/libs/ddInstaller/require.php'
);

// Install (MODX)EvolutionCMS.snippets.ddGetDate
\DDInstaller::install([
	'url' => 'https://github.com/DivanDesign/EvolutionCMS.snippets.ddGetDate',
]);

• If ddGetDate is not exist on your Site, the library will just install it.
• If ddGetDate is already exist on your Site, the library will check it version and update it if needed.

GitLab: Install or update

// Include (MODX)EvolutionCMS.libraries.ddInstaller
require_once(
	$modx->getConfig('base_path')
	. 'assets/libs/ddInstaller/require.php'
);

// Install from gitlab.com
\DDInstaller::install([
	// This is not a valid URL, just an example
	'url' => 'https://gitlab.com/DivanDesign/SomeGroup/EvolutionCMS.snippets.ddGetDate',
]);

Private repository

// Include (MODX)EvolutionCMS.libraries.ddInstaller
require_once(
	$modx->getConfig('base_path')
	. 'assets/libs/ddInstaller/require.php'
);

// GitHub
\DDInstaller::install([
	'url' => 'https://github.com/org/EvolutionCMS.snippets.ddGetDate',
	// Your GitHub Personal Access Token
	'token' => 'ghp_xxxxxxxx',
]);

// GitLab
\DDInstaller::install([
	'url' => 'https://gitlab.com/group/EvolutionCMS.snippets.ddGetDate',
	// Your GitLab Personal Access Token
	'token' => 'glpat-xxxxxxxx',
]);

Links

• Telegram chat
• Packagist
• GitHub