PHPDevShell

Is there a more detailed tutorial for how to use the upgrade feature of a plugin

Asked by tad

Hey, I wanted to let you guys know how much I am loving PDS and how surprised I am it took me this long to hear about it.

Anyways though, I have only made two plugins so far and am still barely starting to understand how everything works in PDS, my question right now being: Is there a more detailed instructional on how to use the upgrade part of the plugins? I read through the beginners tutorial and it helped me understand a great deal, I have also been reading through the Example plugin provided and that has also been a wonderful resource, however I still have not been able to figure out how the upgrade feature works.

I guess my main questions about it are these:
There is the main <version> and I'm assuming that is just to show the user what version it is in a "human readable" form
Then you have the <versionurl current=11> This one I can understand a bit, it checks the xml at the url provided, if it is higher than the current number then it needs to be upgraded

Now the part I don't understand:
<install version="3000"> and
<upgrade version="3003">

First of all, if the current version is say 12(provided in the example at http://www.phpdevshell.org/content/plugin-config-file) then how would the script know to upgrade to 3003? I'm assuming it checks the install version and just installs anything higher than that, but if that's the case how do you set up the new plugin config file in the zip that is downloaded when an upgrade occurs?

do you manually set the install version to the current upgrade version or does the PDS system automatically change the install version as it upgrades them..

I apologize if I am over complicating this but I love the PDS system and really hope to come to understand everything about it to get the full experience out of it.

Thanks for the time and help!

Question information

Language:
English Edit question
Status:
Solved
For:
PHPDevShell Edit question
Assignee:
TitanKing Edit question
Solved by:
TitanKing
Solved:
Last query:
Last reply:

This question was reopened

  • by tad
Revision history for this message
Greg (gregfr) said : 		#1

Thanks for the compliment :) we try very hard to provide a good tool but we lack resources to write a complete documentation.

I personnaly never had to use the upgrade mecanism because I don't release my plugins but I'm sure Jason can explain that.

I'll try however to give you what I understand.

There are in fact 3 different versions count:

- the "human readable" version to be displayed, for example 3.2.5 - only for display
- the "database version" which refer to the data stored in the database
- the "software version" which is the state of the code

Why so many? the first one is quite obvious : you can decide on your own version scheme, which may be very hard for a computer to compare to another. The second is only related to the database, it indicates how the data is stored, where the third is only for the code itself.

For example, version 2.0 of your plugin can be database version 150 and code version 200. When you release 2.0.1 it's very likely the same database can be used without a change. So the plugin version goes up to let's say 210, but the database version is still 150. Now PHPDevShell know it can replace the old code with the new one without upgrading the database. When you release 3.0 you might require a database change (for example you might have added a field somewhere). The database version goes up to 300, which compared to the current 150 means "apply the upgrade sql to the database".

Does it make sense for you?

greg

Revision history for this message
tad (bittiez) said : 		#2

That does make sense, however I'm still lost on how the plugin config file should look on the version that is being downloaded for the upgrade. Also when an upgrade occurs does it replace all the files in the directory with the new files downloaded?

One thing I'm confused about is I don't understand what version is the database one and what version is the software one as there is only one update tag.

Now lets say(to help make things make sense in my head) this is what the plugin file looks like for the database version:
<version>1</version> <-- Just for looks, can be whatever I want

<versionurl current=1>http://blah.com/update.xml</versionurl> <-- Used to check if the current is < the new version
<install version=1>
<-- all the basic install stuff here installed when you install the plugin
</install>

<upgrade version=1>
<-- all the stuff done when upgrade "1" is executed..
</upgrade>

My question would be how does it know when to execute the "upgrade version=1"?

And can you have multiple versions of <install>? If so what is the purpose of the install tags vs the upgrade tags?

I might be narrow minded so forgive me but the only logical way for this to work in my head would be something along the lines of:
if versionurl is < upgrade version
run <upgrade> tags that are > the versionurl
then after the upgrade change the versionurl to the last <upgrade> version it completed

I'm sure that's all completely wrong but it is the only way I can see it working.

Again sorry for the confusion, I'm just very new to using any type of "shell".

Revision history for this message
Greg (gregfr) said : 		#3

<versionurl> is compared to the actual answer from the server; for example, http://version.phpdevshell.org/ExamplePlugin.xml, gives:

<check type="update">
    <version latest="12">3.0.1-Stable</version>
</check>

<install> and <upgrade> are compared to each other. When the plugin is installed and there's no data for it, the <install> clause is used; then the install version is stored. Subsquently, the <upgrade> number is compared to the stored one, if the later is higher, the clause is executed and the new version number is stored.

Better? ;)

Revision history for this message
tad (bittiez) said : 		#4

Okay so if I understand correctly(And please correct me where I'm wrong):
 lets say the update version is 2 and the current is 1
the current plugin file looks something like this(for simplicity):
<versionurl current=1></v url>
<install version=1>
</install>

The next thing that happens is it downloads the new files ->
It then replaces the old files with the new ones ->
Reads through the plugin config which looks something like this(for an example):
<install version=2>
Nothing here is ran because they already had a version installed but this needs to be kept up to date for fresh installs?
</install>
<upgrade version=1>
nothing here is ran because we already had version 1 installed?
<upgrade>
<upgrade version=2>
everything here is ran because the old version was version 1
</upgrade>
Now it updates the store versions and all is well

Revision history for this message
Greg (gregfr) said : 		#5

There is a subtility I'm not quite sure of: I would say that the <upgrade> should contain the version to upgrade *from*, since by definition we always upgrade to the latest version. BUT I'm not sure, you better play a little with that, you can probably find a definitve answer quite easily :)

And don't forget <versionurl> and <install>/<upgrade> are never compared to each other.

Revision history for this message
tad (bittiez) said : 		#6

Alright well after I finish up some school work I need to do ill play around and see what I can figure out. Maybe, if you guys would consider looking it over, ill write up a very detailed tutorial on how it all works for you guys to use in the documentation(If you prefer not to take documents from outside sources though I understand and won't bother writing one up :) ).

Revision history for this message
tad (bittiez) said : 		#7

Okay next problem: I managed to get it to see that it needs to be updated, and it does the "automatic update" however, all this does is download the contents of the zip file to public_html/write/tmp/ and leaves it there, so nothing gets updated in the actual plugin folder, is this normal behavior?

Revision history for this message
Best TitanKing (titan-phpdevshell) said : 		#8

Hi tad, sorry for the late reply, I am going to try and explain it as simple as I can.

There are 2 completely separate parts to an upgrade, the first part would be simple SQL queries updated through the plugin XML file as you have noted in the example plugin. This part is really simple it compares the plugins database version in table "plugin_activation" with the xml version of <install version="3003">, it will then run all the query groups in <upgrade version="3001"> until it reaches 3003 for instance. Note that the content contained inside the tags of <install version="3003"> is for install only, this sql queries best be kept up to date for fresh installs.

So how this will happen is, say for instance I download the latest version of your plugin (104) while I was running (100). I now override the old plugins content. So if I view the plugin manager it will show an upgrade is available seeing that my version <install version="104"> in the new plugin content is newer than what is in the database table marked as (100). So as soon as I hit upgrade it will run all the queries in the 101,102,103,104 upgrade groups.

-------------------------------------

While this is all good, there is one more aspect allowing an option to upgrade remotely. First of all, we dont give write permissions to all writable folders like many other projects do, we believe this is a major security risk. So instead, the file is downloaded to tmp/ directory and then using FTP overwriting the old plugin. So this mean your local FTP server needs to be working, you can set the settings in the General Settings options. However, until we have a smoother working system, I do recommend manually updating the plugins as it probably amounts to the same degree of work.

You will note that the <versionurl current="11"> is independent, that is just a number to compare to the online source to tell the local url version that a newer one is available.

I hope this clears things up slightly.

Revision history for this message
tad (bittiez) said : 		#9

Thanks TitanKing, that solved my question.