HOWTO embark an external dependency in a plugin

albatros69 · 2021-07-09 08:45:55

Hello all,

I’d like to embark an external dependency with my plugin and I understood that distributing it as a zip file would be a possible solution. I may have overlooked something in the documentation, or in the forum, but I didn’t find a description on how to build such a zip file (directory structure and so on).

Or maybe, I’m wrong and there’s a best practice to work with external dependencies and plugins.

Thanks in advance for the help,

Bloke · 2021-07-09 09:33:22

Ah yes the documentation needs to be updated on this, sorry. A distributable package must include your abc_plugin_name.php code file in Textpattern template format OR a raw .php file containing the plugin code only.

If your PHP file is not in template format then you should also include:

A manifest.json file with information such as that given in com_article_image for example. This tells Textpattern the load order, version, flags, description and so forth.
A separate help file: help.textile or help.html. If you wish to host your repo on GitHub, it’s helpful to reference this in the manifest as "help": {"file" : ["./filename.extension"]}.
A separate Textpack for strings as textpack.txp, if your plugin needs them.
An optional file data.txp that will be injected into the database and stored alongside your plugin code. Handy for inserting 3rd party library code or default settings or whatever you want, delimited in any way you wish. You can access this from inside your plugin via Txp::get('\Textpattern\Plugin\Plugin')->fetchData('abc_your_plugin').

After that, anything else you include in the zip file will be extracted verbatim into the plugin’s dedicated subdirectory. You can then reference that from inside your code as usual, providing your plugin directory .htaccess file permits it.

Zip all those files up into a single abc_your_plugin.zip at root level (i.e. NOT inside their own abc_your_plugin directory: Textpattern will make that for you) and you’re good to go.

Hope that helps.

Last edited by Bloke (2021-07-09 14:16:30)

albatros69 · 2021-07-09 13:41:52

OK thanks. I will try ASAP, but that’s easier than expected! :-)

albatros69 · 2021-07-09 20:02:29

Hello all,

I tried to install a zipped version as per your explanation. All is extracted successfully and the manifest.json is read as expected. The only issue I face is that the code, textpack, and help is not extracted from the .php, though I followed the template format. If I’m installing my plugin with the txt format, it works like a charm (meaning the different parts are split nicely).

Is there something I’m missing? For instance, is the code and help order sensitive in the zip process (and not in the txt one)? How can I debug this?

Bloke · 2021-07-09 21:38:27

I made an amendment to my post after I’d thought about it a bit more. In light of what you’ve found I’m wondering if maybe the manifest overrides the template content. So if you’re installing using a template PHP file (which contains everything the plugin needs and therefore doesn’t require the manifest) try omitting the manifest.json and see if that works.

Sorry for the bogus information I gave earlier if so. I thought they could co-exist but maybe it’s manifest+separate files (code, help, textpack, data) OR a single plugin template file. Plus whatever else you want to bundle up, in either case.

etc · 2021-07-10 11:26:12

Yep, currently .php and .zip formats seem mutually exclusive, probably to avoid conflicts. Also, to install from .php source, we actually need to include it on install, which is not ideal for all types of plugins.

albatros69 · 2021-07-10 15:36:15

Bloke wrote #330954:

Sorry for the bogus information I gave earlier if so. I thought they could co-exist but maybe it’s manifest+separate files (code, help, textpack, data) OR a single plugin template file. Plus whatever else you want to bundle up, in either case.

No problem. I know I can ask unusual questions.

Actually, if I package my <plugin>.php file only, it’s not working either. The raw source code is now visible, but no information is extracted from it (load order, etc., and obviously then no help nor textpack). If I read correctly the source code, it seems that any zip file is extracted as is, no matter what

Do you maybe have in mind a plugin packaged this way, so I can look into it and reverse-engineer some details from it? I will likely switch to the “separate files”-pattern, if that would be the solution.

Last edited by albatros69 (2021-07-10 15:37:03)

Bloke · 2021-07-10 17:33:32

Hmmm. Weird. We might have to look into how it works when bundled. Might be an oversight. It could even have already been fixed in 4.9.0 as I’ve made some extensive changes there already.

As for an example, look at etc_cache.

etc · 2021-07-11 08:08:40

I’ve tried installing “com_article_image” from packed .php file and it worked.

etc · 2021-07-11 09:46:25

Mixed php/zip source should work in 4.8.8 now, please test.

albatros69 · 2021-07-13 09:58:40

Hello,

etc wrote #330985:

Mixed php/zip source should work in 4.8.8 now, please test.

Sorry for the latency…
I tried this morning, but unfortunately the 4.8.8 release doesn’t exist yet. I’ve anyway pulled the latest dev version and it doesn’t work: when I upload the zip, I get to a screen with all the bundled files and if I click on install, I get an error (“badly formed or empty plugin code”). However, if I try with the same php file via the txt format, I don’t have any issue (but I miss obviously the dependencies).

Last edited by albatros69 (2021-07-13 15:08:22)

albatros69 · 2021-07-13 15:28:12

Sorry again… I found the 4.8.8 tag and installed it. Importing the zip file works like a charm!
Thanks a lot for the support

Textpattern CMS

Textpattern CMS support forum

#1 2021-07-09 08:45:55