Exact steps to include third-party code with composer and as a git subtree so GPM will be able to install it

#1

I cannot seem to include my composer-installable third-party library in my plugin so that GPM doesn’t cough and spit it out again. I am not sure about what should come first – I shall outline my understanding of the required steps here, let you point out what I have got wrong, and when I have managed to make my plugin installable with the library included, I shall update the docs. (Unfortunately, looking at other plugins with third-party code doesn’t really help me here, because I can’t see how they managed to put it there.)

Exact steps to incorporate a library with composer into a custom plugin and track it all with git:

  1. Create plugin with all the basic files, and add it to git project.
  2. Create directory vendor/ in plugin directory.
  3. Copy the library’s composer.json file into plugin directory.
  4. Run composer.phar install in plugin directory, this will create a whole bunch of files including composer.lock. :question:
  5. Add the whole shebang as a subtree into the plugin’s git project (copying modified steps from this github article:
    1. git remote add -f mynameforthelibrary git@github.com:libcreator/third-party.git
    2. git merge -s ours --no-commit --allow-unrelated-histories mynameforthelibrary/master
    3. git read-tree --prefix=vendor/whatnamegoeshere??/ :question: -u mynameforthelibrary/master
    4. git commit -m "Subtree merged in directory [???]"

Would this work, in this sequence?? Did I get the naming right? In the example they use the same name for everything, but in theory I could name the subtree whatever I want – is that right?

In my project, I confused subtrees with submodules and also copied the whole library into a subdirectory but then installed it with composer as well, and my third-party code incorporation is a mess now. Before I fix this, I would love to have a clear understanding of how to do it properly. Please and thank you so much! :snail:

#2

not long ago, I stumbled over the same question :grinning:
my recent plugin: icalendar depends on om/icalparser .
so, my first approach was try to make gpm install that as a dependency for icalendar.
this didn’t work out, as gpm only installs plugins which have been declared in blueprints.yaml, given these plugins are also in gpm repository.
composer, on the other hand, can be used to install any 3rd party package that is listed in packagist.
note that this has nothing to do with git, github, gitlab or any other git-based repo !
so, conclusion for me was:

  • run composer require <3rd party package>

in my plugin directory, which would fetch composer.json, create and populate the vendor directory, create composer.lock and autoload.php .
note: no .git directory created, so far !
then just add anything new to my github repo.

as a result, everything needed by the new plugin is included in my github repo (and hence in the gpm repo as soon as the plugin is incorporated there).

of course, there is no subsequent auto update for the 3rd party package for users of the new plugin.
it is up to you, the developer, to incorporate updated versions in your plugin, after test, if these still work with your own code.

#3

Hey there, thank you very much for your reply! (And icalendar looks to be super useful, will check that out properly soon!)

By now I have come to a similar conclusion, and I also dug up some interesting links:

So the way I see it now is, I could do it either way: manage my third-party code dependencies with composer OR as a git subtree – I guess it’s up to personal preference and also depends on what the library uses/can be tracked with.

But in all cases I as the plugin maintainer am responsible for getting updates in that vendor library into my plugin, as people who have it installed do not have an easy way to do this themselves. That, I think, is the crucial understanding that I was missing up until now.

I will now attempt to sort out all the subtree-composer confusion in my code, and if I am right, I should be able to finally make my plugin installable via GPM :smiley: and then I’ll try to make this clearer in the docs, because I really do think this is difficult to grasp for people who are new to both composer and git.

Thanks again @hoernerfranz! Oh, and by the way the link to the README file in icalender seems to be outdated (returns 404), you may want to fix that.

#4

yes, you’re right, you should manage 3rd party code via composer (if in packagist) or as a git subtree (I’m not familiar with that) but not a mix of both :wink:
and, as said, you as a developer are responsible for having incorporated a working version in your plugin.
If gpm, for example, would make automatic updates of 3rd party code in plugins, there would be a big chance to break things.
plus, documentation why you did something in a specific way, is always good .
finally, I’m not sure about the 404 for README in icalendar, I can see it without problems here

#5

Sorry, I didn’t make myself clear with that. In your blueprints.yaml for icalendar, the link to the README file is outdated. This is the one that gets pulled in the Grav plugins download section, so when you bring up icalendar there and click on “docs”, you get a 404 error.

And MAN, I just had the f*ckiest hour getting rid of that old submodule I had introduced at some point – NEVER, ever use submodules for third-party dependencies! Ugh. It should be gone now though, and working alright hopefully to probably :wink: but somehow I also managed to pull up a whole bunch of tags from the Cloudinary code, and now my plugin is listed as having 42 releases. exasperated SIGH

Not sure I can do anything about that though, and since they’re all older than my new correct ones, it shouldn’t be an actual problem. I’ll cross my fingers and pray that won’t come back to bite me in the butt some time… :laughing:

EDIT: I can actually delete them. Whew!

#6

ok, you’re right, all the links in blueprints.yaml were 404’s :woozy_face:
fixed now, thanks for notification !