Cash flow, debts, period closing

🌐 Language: 🇻🇳 Tiếng Việt · 🇬🇧 English (current)

Installing Plugins & Templates for GP247

Introduction

This document explains how to install a plugin or template (collectively called an extension) into a GP247 website, aimed at site owners — including non-technical ones. GP247 supports 4 installation methods: install online via the official extension library, import a ready-made .zip file, install manually by copying the folder onto the server, or use the command line (gp247:ext-*) for developers/automation. By the end, you will know which method suits you and how to follow each step.

💡 Plugins and templates install exactly the same way — the same methods. The only difference is that they live under two different admin menus: Plugin and Template. Wherever this document says "extension", it applies to both.

1. Before you install — what you need to know

You must log in to admin with an account that has permission to manage extensions.
The extension must be compatible with your website. On install, GP247 automatically checks the 3 conditions declared in the extension's gp247.json:
- requireCore: the required gp247/core version (the current standard is 3.0).
- requireComposerPackages: mandatory packages (for example, a template always needs gp247/front).
- requireGp247Extensions: other extensions that must be installed first.
Since gp247/core 2.1, the keys requireComposerPackages/requireGp247Extensions replace the old requirePackages/requireExtensions. Core 2.1 still reads the old keys (backward compatible) but they are deprecated.

If any condition is missing, GP247 reports an error and refuses to install — install the missing part first.
After installing, GP247 clears the cache automatically (routes/config), so you don't have to do it by hand. For a template, after installing you must also activate it on the Website information screen (see section 6) for the look to take effect.

Quick glossary:

Extension: the collective name for plugins and templates.

gp247.json: the file declaring the extension's info (name, version, compatibility conditions).

configKey: the extension's unique identifier, the same as its folder name.

2. Method 1 — Install Online (via the extension library)

This is the easiest way: browse GP247's official extension store right inside admin and click to install, with no manual file download.

💡 No admin access, or want to install from a script? The same library works from the command line — see section 5.1.

⚠️ This method only appears if your website has the GP247 library connection enabled (the api_plugins config for plugins / api_templates for templates is on). If you don't see the Online menu, use Method 2 or Method 3.

Step 0 (do it once) — Register an API License to connect to the library

Before you can browse the extension store, your website needs an API License to identify itself to the GP247 library. This license is free.

In admin, open API License settings (Register / Install API license) — usually inside the Online screen of Plugin/Template.
Click Register / Install. GP247 contacts the library and fetches a license key for your domain.
On success, this key is automatically saved into the GP247_API_LICENSE variable in the .env file at the website root. You do not need to edit .env by hand.

Once GP247_API_LICENSE is set, your website is connected to the library — move on to the install steps below. Step 0 is a one-time task; later installs don't require repeating it.

ℹ️ Distinguishing the two license types:

API License (Step 0, free): the key for your website to connect and browse the library. Stored in GP247_API_LICENSE.

Paid extension license: a separate license for each paid extension, needed only when downloading a paid extension (see the end of this section).

The online install steps

Log in to admin. Go to the Plugin (or Template) menu, then choose the Online submenu (extension library / store).
The list of extensions from the GP247 library appears. You can search by keyword, filter free / paid, and sort. Each extension shows its name, version and price.
Choose the extension to install and click Install.
GP247 automatically: downloads the file → checks compatibility → extracts → installs. On success you see an install-successful notice and the extension appears in the installed list.

About paid extensions: besides the free API License in Step 0, a paid extension also needs a license specific to that extension (issued for your domain after purchase). If you don't have one, admin guides you to activate the license before downloading. Free extensions download and install right away, with no separate license (just the Step 0 API License).

3. Method 2 — Import (upload a `.zip` file)

Use this when you already have the extension as a .zip file (bought outside the library, received from a developer, or packaged yourself). You upload this file through admin, and GP247 extracts and installs it automatically.

Steps:

Go to the Plugin (or Template) menu and choose Import (Upload).
Select the extension .zip file from your computer, then click Upload / Import.
GP247 checks and installs it automatically. On success, the extension appears in the installed list.

Requirements for the .zip file:

Must be a proper .zip (not .rar, .7z...).
Maximum size 50MB (and not exceeding the server's upload limits — upload_max_filesize / post_max_size in PHP).
The .zip must contain a gp247.json file (otherwise GP247 reports a "wrong configuration" error).
It must not duplicate an already-installed extension: if the configKey already exists on the site, GP247 refuses it to avoid accidental overwrites. To upgrade to a newer version, use the update feature, not import-over.

ℹ️ Small note: after importing a template successfully, the screen may return to the Plugin list instead of the Template list (this is a current characteristic of the system). Don't worry — the template files are installed correctly into the template folder; just go to the Template menu to see it, then activate it on the Website information screen (section 6).

4. Method 3 — Manual install (copy the folder onto the server)

Use this when you have file access to the server (FTP, SSH, or your hosting's File Manager) and want to place the extension directly — usually for developers, or when the two methods above aren't available.

Steps:

Copy the whole extension folder (the folder containing AppConfig.php and gp247.json) to the right location on the server, depending on the type:
- Plugin → app/GP247/Plugins/<ExtensionName>
- Template → app/GP247/Templates/<ExtensionName>
Here <ExtensionName> must exactly match the configKey declared in gp247.json.

For example, a plugin whose configKey is MyBanner goes into:
```
app/GP247/Plugins/MyBanner/
├── AppConfig.php
├── gp247.json
└── ...(the remaining files)
```
The extension's public/ folder (css/js/images) does not need copying by hand: when you click Install in step 4, GP247 copies it to public/GP247/Plugins/<ExtensionName> (or public/GP247/Templates/<ExtensionName>). Since the 2026-09-27 update; older versions still need the manual copy.
In admin, open the Plugin (or Template) menu. The extension you just copied will appear automatically in the list (GP247 scans the folder to detect it). It is in the not-installed state.
Click Install next to that extension. GP247 checks compatibility, then installs. On success, the button switches to the installed state.

⚠️ The extension folder must contain AppConfig.php — GP247 relies on this file for detection. If you copy without this file, the extension will not appear in the admin list.

Moving to a newer version by copying over it (or git pull). Copying the new release over the old folder replaces the files only; the new release's data update has not run yet.

ℹ️ Available since: the 2026-09-29 update

After copying, open the Plugins (or Templates) list again: the extension carries a yellow "Data update pending: x → y" badge in the Version column. Click its Apply data update button (database icon), or run php artisan gp247:update. Details: How to update GP247 — section C.

5. Method 4 — Command line (`gp247:ext-*`)

For developers, CI/CD, Docker or shared hosts with terminal access, the whole extension lifecycle is available from the command line — the same engine the admin UI uses (so compatibility checks, GP247_PROTECTED_* and the in-use/default-template guard all apply identically). Plugins and templates share one command family; choose with --type=plugin|template.

5.1. Install online from the library on the command line (gp247 3.x)

This is Online (Method 1) done in a terminal: no admin needed, handy when a site is built by a script or in Docker. Run in the website's root folder:

# 1) Once per website: register the (free) API License — the same as Step 0 of Method 1
php artisan gp247:ext-register-license

# 2) Download a free extension from the library and install it (key = the extension's configKey)
php artisan gp247:ext-install --type=plugin --key=News

# Paid extension: add that extension's own license, and install one key at a time
php artisan gp247:ext-install --type=plugin --key=ProPlugin --paid --license=<your-license>

# Template: same command, different --type (still has to be activated afterwards, see section 6)
php artisan gp247:ext-install --type=template --key=<TemplateName>

Before step 1, set APP_URL in .env to the website's real domain (not http://localhost) — the license is bound to that domain; with the wrong domain every later library call is refused.
ext-register-license writes the key to GP247_API_LICENSE in .env. If .env is not writable (some shared hosts lock it), the command prints the key so you can paste it yourself into .env — keep it secret, do not commit it.
If ext-install fails with a license/domain error, it suggests re-running gp247:ext-register-license.
An installed plugin is enabled and caches are refreshed automatically. An installed template still has to be activated on the Website information screen — there is no command for that step (section 6).
An extension whose files are already on disk but not installed (copied manually, or shipped with the installer) → --key installs it in place instead of downloading it again.
Newer version: php artisan gp247:ext-update --type=plugin --key=News (or --all).
Already replaced the files with git pull/Composer/a manual copy: add --local to download nothing and only run the missing data update — php artisan gp247:ext-update --local --type=plugin --key=News (or --all; add --dry-run to preview). Available since the 2026-09-29 update.
Mandatory composer packages (requireComposerPackages, e.g. laravel/socialite)? composer require them first — ext-install only checks them, it does not install composer packages.

5.2. Other extension lifecycle commands

# List local extensions + status + available updates
php artisan gp247:ext-list --type=plugin

# Install from a local .zip, an extracted folder, or the marketplace (by key)
php artisan gp247:ext-install --type=plugin --file=storage/tmp/MyBanner.zip
php artisan gp247:ext-install --type=plugin --key=News

# Enable / disable / uninstall (accept multiple keys)
php artisan gp247:ext-enable  --type=plugin --key=News
php artisan gp247:ext-uninstall --type=plugin --key=News

# Update from the marketplace (one, or all with an available update)
php artisan gp247:ext-update --type=plugin --all

# Files already replaced by git pull / composer / a manual copy: run only the data update
php artisan gp247:ext-update --local --all --type=plugin --dry-run
php artisan gp247:ext-update --local --all --type=plugin

# Search the marketplace; manage a paid extension's license
php artisan gp247:ext-search --type=plugin --keyword=blog
php artisan gp247:ext-license --type=plugin --key=ProPlugin --license=XXItXX

Notes:

Add --json to any command for a machine-readable envelope ({ok,command,data,warnings,error}) with a standard exit code (0 success / non-zero failure) — ideal for scripts and CI.
Batch: ext-install/enable/disable/uninstall accept multiple keys (--key=A --key=B or --key=A,B); items run one at a time and independently, the cache is rebuilt once at the end, and the command exits non-zero if any item failed. Install a paid extension one key at a time.
Re-running is safe: ext-install refuses an already-installed extension (use ext-update to update, ext-uninstall to reinstall).
Full reference: command-line-reference.md.

6. After installing — activate and verify

For a plugin: it is usually ready to use after installing. Some plugins have Enable/Disable and Config buttons — adjust them if needed.
For a template: once installed, the template is only present on the site. To make a store use it, activate it: in admin go to System management → Website information, pick the template in the Template field, then confirm. Each store uses one template; a multi-store site (MultiStore) picks one per store.

⚠️ Switching template deletes the old template's home-page layout blocks and banners, then seeds sample data for the new one. This cannot be undone, which is why the admin always asks you to confirm first. Re-picking the template already in use changes nothing.

ℹ️ The command line has no command that activates a template for a store: gp247:ext-enable --type=template only enables the template's config row, and gp247:template-setup only applies the default template (GP247_TEMPLATE_FRONT_DEFAULT) to the root store. Activation is always done in the admin.
GP247 clears the cache after installing. If for some reason the look/feature isn't updated, run the following command at the website root to clear the cache manually:
```
php artisan optimize:clear
```
Open the website (or the related admin screen) to check the extension works correctly.

7. Which method should I use? (quick comparison)

Method	When to use	Advantage	Requires
Online	Want to browse & install quickly from the official store	Easiest, fully automatic	Site with library connection on; a license for paid ones
Import	You already have the `.zip` file	No server access needed	A valid `.zip`, ≤ 50MB, containing `gp247.json`
Manual	You have server file access / the two methods above aren't available	Full control, no upload/API dependency	FTP/SSH/File Manager access; copy to the right folder
CLI (`gp247:ext-*`)	Developers, CI/CD, Docker, scripted/batch installs	Scriptable (`--json` + exit codes), batch multiple items, same engine as UI	Terminal access at the project root

8. Common troubleshooting

Compatibility error on install: a requireCore / requireComposerPackages / requireGp247Extensions condition is missing. Install the missing part (e.g. install gp247/front before a template) and retry.
Import reports "wrong configuration": the .zip doesn't contain gp247.json at the right level, or you zipped it wrong (an extra parent folder layer). Check the archive structure.
Import reports a duplicate: the extension is already installed. To go to a newer version, use the update feature, don't import over it.
Manual install but admin doesn't show it: check that you copied to the right folder (app/GP247/Plugins vs Templates) and that the folder has AppConfig.php; then run php artisan optimize:clear and reload admin.
Installed, but the extension's screens look broken (no styling, buttons do nothing, images missing): its static files (css/js/images) never reached public/. Typical on sites that installed an extension by copying its folder before the 2026-09-27 update. Run php artisan gp247:doctor — the extension_assets line names the affected extensions — then php artisan gp247:ext-publish --type=plugin --key=<ExtensionName> (--type=template for a template, or --all for every one).
The .zip file is too big to upload: over 50MB or over the server's upload limit. Use Method 3 (manual) instead.

9. Q&A

Q1: Is installing a plugin different from installing a template?

→ The installation is identical (the same methods). Only the place differs: plugins under the Plugin menu, templates under the Template menu. A template additionally has to be activated under System management → Website information after installing for it to take effect.

Q2: I don't see the "Online" menu in admin?

→ Your website hasn't enabled the GP247 library connection (api_plugins/api_templates). Use Method 2 (Import) or Method 3 (manual).

Q3: What's the first thing to do to use the online library?

→ Register the API License (free) once in admin — see Step 0 in Method 1. This key is auto-saved into the GP247_API_LICENSE variable in .env, letting your website connect and browse the extension store.

Q4: How do I install a paid extension?

→ Install it online as usual, but besides the free API License, a paid extension also needs a separate license for your domain (after purchase). Free extensions don't need one.

Q5: What structure must the .zip have to be importable?

→ The .zip must contain a gp247.json file (along with AppConfig.php and the extension's files). Don't add an extra parent folder layer that pushes gp247.json too deep. The file must also be ≤ 50MB; larger than that, install manually.

Q6: I installed manually but admin doesn't show the extension?

→ Check: did you copy to the right folder app/GP247/Plugins/<Key> or app/GP247/Templates/<Key>, does the folder have AppConfig.php, and does <Key> match the configKey in gp247.json? Then run php artisan optimize:clear and reload the admin page.

Q7: Why does importing a template jump back to the Plugin list?

→ This is a current characteristic of the system — the template files are still installed in the right place. Just go to the Template menu to see it, then activate it on Website information (section 6).

Q8: Do I have to clear the cache manually after installing?

→ Usually not — GP247 clears the cache after installing. If it isn't updated, run php artisan optimize:clear.

Q9: Can I install a new version over the old one by importing?

→ You shouldn't. Import refuses if the configKey already exists. To go to a newer version, use the update feature — it preserves the settings stored in the database. If you copy the files over by hand or with git pull, click Apply data update next to the extension (or run php artisan gp247:update) so the new release runs its data part.

Q10: How do I uninstall/delete an extension, and how do I avoid accidentally deleting the source?

→ The extension list has 2 deletion levels: "Delete data" (removes only the data/config in the database, keeps the source files) and "Remove files" (removes both the data and all source files on the server). Note: you can't delete a template that's currently active (switch to another template first).

To guard against accidental deletion of important extensions, GP247 has a protection mechanism: declare their configKey in the GP247_PROTECTED_PLUGINS (for plugins) and GP247_PROTECTED_TEMPLATES (for templates) variables in .env, comma-separated. For example:

GP247_PROTECTED_PLUGINS="Payment,ShippingVN"
GP247_PROTECTED_TEMPLATES="GP247Front"

For a protected extension, admin hides both the "Delete data" and "Remove files" buttons — meaning it cannot be uninstalled or deleted from the interface, preventing source/data loss from a mistaken action. To actually remove it, take its name out of the corresponding .env variable and try again.

On the command line, the two deletion levels map to gp247:ext-uninstall --type=... --key=... (installed → removes data and files) and gp247:ext-uninstall ... --only-data (removes data only, keeps files). An extension that is not installed but still on disk (e.g. a bundled plugin) is refused unless you add --purge (which then deletes just its files). The CLI honors GP247_PROTECTED_* and the in-use/default-template guard just like the UI — a protected or in-use extension is refused with a clear error even with --purge.

Change history

Date	GP247 version	Change
2026-09-29		Replacing an extension's files by hand / `git pull` / Composer: the list shows a "Data update pending" badge and an Apply data update button; new `gp247:ext-update --local` command (sections 4, 5).

_{📅 Last updated: 2026-09-29 · ✍️ Author: GP247}