Easily add support for the Sparkle upgrade mechanism for Mac OS X applications to your CakePHP website. JDSparkle will:
- Serve your AppCast xml files to the Sparkle updater.
- Serve your update notes to Sparkle clients via Cake standard view files using the template of your choice.
- Log system profiling data to your database if provided as part of
of the xml request.
- Supports any arbitrary tags in addition to Sparkle's defaults.
- Some rudimentary reporting of all system profiles with support for all data or a day-limited range. Also tries to limit results by unique IP address to help filter out frequent update checks.
Tested with configuration below, and may or may not work in earlier releases:
- PHP 5.2+
- CakePHP 2.3+
- A Sparkle-enhanced application for Mac OS X. Sparkle ports for other platforms should probably work as well.
http://balthisar.github.io/JDSparkle
- Download this: https://github.com/balthisar/CakePHP-JDSparkle/archive/master.zip
- Unzip that download.
- Move or copy the
JDSparkle
directory into yourapp/Plugin directory
.
If you’re aware of this option then I presume you already know how to use git and Github.
CakePlugin::load(array('JDSparkle' => array('routes' => true)));
By defaults JDSparkle attempts to use the database connection JDSparkleDB
,
which is probably not setup in your database. You can either add it to your
app/Config/database.php
or change the $useDbConfig
settings in the
two model class files JDSparkleRecord.php
and JDSparkleReport.php
.
Finally import the schema file from the CakePHP shell:
cake schema create --plugin JDSparkle
If you'd like to generate some fake, sample data for testing the reporting
features, you can (using the supplied default routing) navigate to
http://www.example.com/softwareupdates/randomdata/secretpassword
.
You should set up your own security system using CakePHP access control lists.
For convenience JDSparkle ships with an unsafe password system that's sent as
clear text. In the class file JDSparkleReportsController.php
you should
set the variable $secretpassword
to a null string to turn off this feature.
If you'd like to use this feature on your testing server, then at least consider
changing the default from "secretpassword" to something else.
- The sample code will use
www.example.com
as the web host. Obviously use your own server. - The sample code will use
softwareupdates
as the main path to access the controller. You can considering changing this plugin's routes to point to any path that you want. - For admin type actions, they will be shown using the "secretpassword" as described above. Once you've set up your own authentication, simply omit the password from your URL's.
- The application using Sparkle will check for updates using the url
http://www.example.com/softwareupdates/updatecheck/appnameFile
.- Note the absence of the
.xml
extension. - This is the value you should place in the
SUFeedURL
in your application'sinfo.plist
file. - As currently implemented, JDSparkle will not log IP data for these types of requests.
- Note the absence of the
- If you are collecting system profiling information then the suitable
GET request will be similar to
http://www.example.com/softwareupdates/updatecheck/appnameFile?appName=xxx&?…
.- Note the absence of the
.xml
extension. - This is the value you should place in the
SUFeedURL
in your application'sinfo.plist
file.
- Note the absence of the
- Your XML appcast files must be placed in the plugin's
View/AppCasts
directory asappname.ctp
. See the section below about "Potential cause for confusion."- Remember that
.ctp
files are PHP files. Some PHP configurations might interpret your<?xml
declaration as a PHP declaration and you will be unhappy. To be safe simply echo the<?xml
declaration with PHP.
- Remember that
- Your release notes must be placed in the plugin's
View/AppReleaseNotes
directory matching the what you have in the appcast XML<sparkle:releaseNotesLink>
tag.- The
<sparkle:releaseNotesLink>
tag should have the URL in a form similar tohttp://www.example.com/softwareupdates/releasenotes/appnameVersionXXX
. - Again per Cake conventions the URL typically does not have a file extension, as this is just a normal CakePHP view.
- The default CakePHP layout for these files is "blank.ctp" but you can change this in the controller.
- The
- Finally the update package should be placed anywhere on your server that
can be served via your CakePHP application, typically somewhere in
app/webroot
. There's no special configuration for this that's any different than Sparkle's normal configuration. That is, in your XML<enclosure
point to the update package just as your normally do.
Note that above the use of "appnameFile" applies to URL request that Sparkle itself makes (and the file system representation). It is not specifically related to the "appName" request parameter that Sparkle will provide if you are using system profiling.
However the admin actions do use the "appName" request parameter in their requests, since this is how they're identified in the database.
-
updatecheck
as described above. -
releasenotes
as described above. -
randomdata
as described above. -
overview
is an admin function that provides an overview of all of your apps' collect profiling information. It can be accessed athttp://www.example.com/softwareupdates/overview/secretpassword
. -
details
is an admin function that provides specific details for a single app for which JDSparkle has collected profiling information. Access it athttp://www.example.com/softwareupdates/details/appname.app/secretpassword
.- Note: in this case, the field
appname.app
is not the same as the appnameFile described further above. It is the value of the appName request parameter that Sparkle sends as part of the GET request when profiling is enabled.
- Note: in this case, the field
The source code is fairly verbosely documented. You don’t have to understand the source code, but please read all of the comments at the top of the main files.
Copyright (c) 2013 by Jim Derry
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.