README

The library for installing and updating snippets, plugins, and libraries from GitHub 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 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.62
• (MODX)EvolutionCMS.snippets.ddMakeHttpRequest >= 2.3

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 URL.
    • E. g. 'https://github.com/DivanDesign/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' 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: —

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

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.

Links

• Telegram chat
• Packagist
• GitHub