Here we keep track of backward-incompatible changes.
For every (necessary) backward-incompatible Garp update we create a new tag, with an incremented minor version number.
(not entirely semver-compatible, we know, but historically more compatible with how we came to Garp version 3 in the first place)
Garp is now compatible with PHP 8.0.
The minimally required version is PHP 7.4.
Mostly thanks to upgrading these dependencies:
- fzaninotto/faker: using
dev-master, so make sure yourminimum-stabilityis set todevto allow this. - phpunit: a ton of assertion methods, as well as the
@expectedExceptiondirective in docblocks, have been removed, so make sure you're not using those. You'll know because your test suite will fail. - shardj/zf1-future: should be backward-compatible, but your mileage may vary. We had to update the loading of filters in
Garp_Form_Element_Emailfor instance, due to aReflectionClasspeculiarity.
Removed support for Dotenv version 4.
You're unlikely to notice a difference, but if you load env files yourself, please update your calls to use createUnsafeImmutable. See also DotEnv's Upgrading Guide.
Upgrade Garp\Functional to the latest version.
Make sure you don't use the match function anymore, since it conflicts with PHP 8's match keyword!
Monolog is not used by Garp and therefore removed. Before upgrading, add monolog/monolog:^1.0 to your projects composer.json, if you use Monolog.
Remove support voor phpdotenv 3 and add support for version 4 and 5. When your application calls phpdotenv (not very likely) follow the upgrade instruction provided by phpdotenv: https://github.com/vlucas/phpdotenv
PHPUnit is now a dev dependency. When your application composer.json doesn't require phpunit/phpunit add "phpunit/phpunit": "^6|^7" to require-dev.
Composer 2 compatibility is finally there. autoload rules in composer.json have been changed. Some classes previously loaded by PSR-0 have been moved to classmap, because Composer 2 is stricter about PSR-0 class loading. Garp uses an old version of phpoffice/phpexcel, this package is not compatible with PHP 7.4 and Composer 1. By including it in the repository, changing autoload rules and fixing some PHP 7.4 syntax errors the package is working again.
When upgrading to this version:
- Run Composer 1
composer dumpautoload --optimize, all autoloading warnings from Garp should be gone. All warnings should be fixed before your application can use Composer 2. - Test code that uses
phpoffice/phpexcel.
We advise you to refactor code that's using
phpoffice/phpexcelto usephpoffice/spreadsheetinstead.
Custom HTTP calls to AWS API are replaced by AWS SDK for PHP calls to add support for signature version 4. So Garp_Mailer uses AWS SDK for PHP instead of Zend http client. No breaking changes, but Garp_Mailer will throw SesException's instead of Exception.
When the key host is in your AWS configuration remove it and replace it by region with the region part from the original host.
Guzzle 5 isn't compatible with PHP 7.3 and above. Garp now requires Guzzle 6 or 7.
Deprecated:
Garp_Service_Amazon_Ses->sendEmail()useGarp_Mailer->send()Garp_Service_Amazon_Ses->sendRawEmail()useGarp_Mailer->send()
Removed:
- Cli command:
g ses Stats
The functionality previously found in Garp_Test_PHPUnit_TestCase is now in Garp_Test_Traits_UsesTestHelper.
This allows you to extend other TestCase parent classes (like the one provided with Laravel), while still keeping Garp functionality.
Hopefully this eases the transition to or integration with other frameworks.
PHP 7.4 compatibility has arrived 🥰
Some dependencies got a higher minimal version. When you use lower versions update and test them.
- ezyang/htmlpurifier from
^4.8to^4.12 - fzaninotto/faker from
^1.8to^1.9.1 - phpunit/phpunit from
^6.0|^7to^6|^7 - shardj/zf1-future from
^1.14to^1.16.2
Removed the need for a class docblock from phpcs.xml. In modern development environments all information is in a version control system. We don't think it's required anymore to have a docblock.
Obviously add one yourself when an explanation of the class is warranted.
Hostname validation has been enabled for Garp_Form_Element_Email. Only the local part of the email address was validated. Now domains (except localhost) are allowed, IP addresses are not allowed.
To restore the behavior for one email element overwrite the validator:
$validator = new Zend_Validate_EmailAddress();
$validator->setOptions(array('domain' => false));
$emailElement->addValidator($validator);To restore it for the whole application create a custom email form element.
class App_Form_Element_Email extends Garp_Form_Element_Email {
public function init() {
$validator = new Zend_Validate_EmailAddress();
$validator->setOptions(array('domain' => false));
$this->addValidator($validator);
}
}Create an App_Form class which contains the location of your custom form elements.
class App_Form extends Garp_Form {
public function init() {
parent::init();
$this->addPrefixPath('App_Form', APPLICATION_PATH . '/../library/App/Form');
$this->addElementPrefixPath('App', APPLICATION_PATH . '/../library/App/');
}
}Let your form extend from App_Form.
class My_Form extends App_Form {
public function init() {
parent::init();
$this->addElement('email', 'user_email');
}
}Garp_Db_Table_Rowset methods filter and map will pass an actual row object into the callback, as opposed to an array.
This will break existing implementations that rely on the argument being an array.
To enable Garp projects to use PHP v7.3 we needed an updated version of Zend Framework 1. Since it is discontinued we rely on a community supported fork of zf1, shardj/zf1-future, that has replaced all v7.3 deprecated functions. It is intended to adapt to future versions of PHP as they are released.
This does not break Garp for projects still using PHP <v7.3.
The functions partial(), snippet() and __() where moved to \Garp\ namespace in 3.19.0, but not added to removed-functions.php. To make removed-functions.php a complete drop-in fix when upgrading to v.3.19 the functions where re-added to that file.
Change API response Content-Type to application/json.
Add spawn input property searchable.
vlucas/phpdotenv has been upgraded from v2.0.1 to ^v3.4. An overview of parsing modifications can be found in vlucas/phpdotenv/UPGRADING.md. Check your .env file for possible consequences.
To prevent conflicts between Garp3 and Laravel some global functions have been removed. Most of the functions could be replaced by their Garp Functional equivalent. Some need more attention. The original functions still exist in application/removed-functions.php. You could include that file to stay compatible.
# composer.json
"autoload": {
"files": [
"vendor/grrr-amsterdam/garp3/application/removed-functions.php"
]
}
To become compatible with Laravel you can't use removed-functions.php. view() and some other functions are also implemented by Laravel helpers. Which causes conflicts.
Removed functions:
__()*array_get()array_get_subset()array_pluck()array_set()callMethod()callLeft()callRight()compose()concatAll()dump()getProperty()id()instance()model()noop()not()partial()*propertyEquals()psort()snippet()*some()unary()view()when()
* Moved to \Garp namespace.
Removed polyfills:
array_column()gzdecode()
Sentry has been updated to version 2.
This means any manual Sentry error reporting should be updated. Sentry's own changelog is the best place to start.
Also: the entry RavenClient in Zend_Registry has been removed.
Not a breaking change, but because of the huge impact on deploy performance interesting to mention nonetheless: as of this version you can configure Capistrano to not distribute assets to the CDN.
Put the following in the stage's deploy configuration file, or the general deploy.rb:
# staging.rb, for example
:set distribute_assets, falseNote: obviously, if you rely on assets being on the CDN, this setting is not for you.
This works when you have configured your cdn.location to be local, for all file types relevant to you. For instance:
cdn.css.location = "local"
cdn.js.location = "local"
The minimum-stability of Composer packages installed by Garp has changed from dev to stable. Because prefer-stable was in place the impact should be minimal. Nevertheless carefully check and test the changes after running composer update in your project.
Removes the DefaultSortable behavior. It caused more errors than it gave value.
How to migrate models using this feature?
- Check for models specifying the
orderproperty in their spawn configuration. - For every model, check their queries and add an
ORDERclause manually.
Note: the CMS is not affected, since the order is still stored in the Javascript models.
The Zend Framework Amazon S3 service has been severed from Garp: it now uses the official AWS PHP SDK from Amazon to interact with the S3 service.
Nothing has changed, all interfaces and outputs have remained the same, however, cdn.s3.region has become a required configuration parameter.
The minimum required PHP version has been updated to PHP7.1.
Mostly to be able to support Garp\Functional version 3.
teardown on our unit test has been greatly optimized to allow for high-precision truncating.
The teardown method will truncate exactly the tables that received inserts during the tests, no more, no less.
In order to use this functionality, you need to make sure your default database adapter has a profiler enabled:
[testing : development]
resources.db.params.profiler.enabled = true
resources.db.params.dbname = "my_test_database"
This way we can piggyback on the profiler to keep track of all INSERT queries.
When no profiler is configured, the old behavior will still work.
One notable backward-compatible change is the removal of getDatabaseAdapter() from Garp_Test_PHPUnit_TestCase.
It has been moved to Garp_Test_PHPUnit_Helper, so if you still want to use it, do so thru $this->_helper->getDatabaseAdapter().
Using Capistrano, we write a VERSION file in the root of the project. An accompanying Garp_Version class is created to lookup the current version.
Note that this file will usually not exist in development environments, so don't write code which relies on it.
This deprecates the use of Garp_Semver. Since this is mostly used to aid the git flow helper commands, this version of Garp will be most compatible with a One Flow setup. See OneFlow - a Git branching model and workflow
for more information.
In addition, some spring cleaning has been done:
Garp_Util_AssetUrlhas been greatly simplified. Either you use arev-manifestfile or you get a versioned query string added to the file (containing the version stored inVERSION). All code related to using versioned build paths has been removed.git flow-related code has been deprecated. This meansg feature,g hotfixandg releaseare no longer valid Garp CLI Commands.Garp_Semverhas been removed.
In order to update the phpunit dependency to a modern version, we finally dropped support for php 5.3 and jumped all the way up to php 7.
Most importantly for implementors: Garp_Test_PHPUnit_ControllerTestCase has been removed from Garp. It extended Zend_Test_PHPUnit_ControllerTestCase, which was the reason we couldn't upgrade phpunit.
Previously, we used a boolean in Zend_Registry to indicate CMS context:
Zend_Registry::set('CMS', true);This setting is deprecated. Garp now happily continues life with one less global variable to worry about.
If you want to know if a model's being used in CMS context, you can access the new isCmsContext method of Garp_Model_Db. For instance in a behavior's callback:
function afterFetch($args) {
$model = $args[0];
$isCms = $model->isCmsContext();
}If your app uses Zend_Registry::get('CMS') it will need to refactor that bit.
Since credentials for CDNs moved to .env files, g cdn distribute is no longer able to distribute to the right environment, since the credentials are not known across envs anymore.
12g is developed to fix this. It can read configuration from other environments, among other things.
Its output can be piped into Garp to distribute to the right environment, like this:
12g env list -e staging -o json | g cdn distribute
A little late to the party, but as of this version 12g is a requirement for Garp deployment using Capistrano. The --to parameter of g cdn distribute is officially deprecated and will trigger a warning.
Asset URL generation has changed once more. Fortunately, is has been greatly simplified. There's no more attempted intelligence in constructing an s3 URL at either HTTPS or HTTP, with or without a bucket, on a custom domain, et cetera.
All you have to do is configure:
cdn.baseUrl = "https://s3-eu-west-1.amazonaws.com/bucket"
That's it. Provide everything up to the paths that are fed to the assetUrl helper at runtime.
Note that nothing changed to the path manipulation logic, so versioning or hashing still works.
Also, local exceptions for assets are still allowed:
cdn.baseUrl = "https://s3-eu-west-1.amazonaws.com/bucket"
cdn.css.location = "local"
This still puts CSS files on a relative path (/css/base.css) but uploaded files will be loaded from the external domain (https://s3-eu-west-1.amazonaws.com/bucket/uploads/images/funny-monkey.gif).
When memcached is configured, it HAS to be running, otherwise an exception is thrown. Sounds fair, right? In the past however, Garp would fallback to the BlackHole cache if Memcache was unavailable.
We want to be explicit in our behaviors rather than implicit, therefore this was changed. You can simply configure Memcached to be NULL and no connection attempts are made.
// @file application/configs/environment.php
$memcachedPorts = array(
'production' => 11211,
'staging' => 11211,
'development' => null,
'testing' => null
);
// @file tests/TestHelper.php
define('APPLICATION_ENV', 'testing');
define('MEMCACHE_HOST', null);
define('MEMCACHE_PORT', null);
Note that this is not considered to be a breaking change because historically, all production and staging environments are configured correctly. It's only local development machines that are hurt by this. The fix is so easy that I trust devs to make quick work of this nuisance.
Garp will look for composer.phar in the shared folder when deployed with Capistrano. If it's there, it will execute composer install. This allows you to put the entire vendor folder inside .gitignore.
Take a look at this script to find out how to install Composer on the server
Note: in a clustered environment every webserver should have its own composer.phar.
Also: development machines are pretty rad and run things like PHP 7. Webservers sometimes are kinda wack and run things like PHP 5.3.
You can configure the following in composer.json to make sure you never install dependencies that cannot run in the target environment:
"config": {
"platform": {
"php": "5.3.3"
}
}
Tiny change that should not really affect you but might still: the cache directory for HTMLPurifier must be configured explicitly.
htmlFilterable.cachePath = APPLICATION_PATH "/data/cache/htmlpurifier"
Note that it's also recommended to specify something nested inside application/data/cache. In the past its URI, HTML and CSS directories ended up directly inside /application/data/cache, but in order to namespace everything a bit more neatly, let's use a dedicated folder. (incidentally: this is also the directory that Capistrano will auto-create on the web server)
If not configured, no path will be specified to HTMLPurifier.
Translatable behavior has been refactored. (See commit https://github.com/grrr-amsterdam/garp3/commit/4d200b62d5d70f8b0a08499e683d10c47baaf6ef)
Because of this change, the database of multilingual projects needs an update. The fallback system is gone, so data needs to be migrated from the default language to all others.
A CLI command is provided for this purpose:
g i18n populateLocalizedRecords
Note that the process reads every multilingual record in your project and migrates its content to the accompanying record in every other language. It might take a long time to finish.
Also, a tiny change is made to reflect recent Gulp setups. Projects are now required to have both a assets.js.root and a assets.js.build directory.
It used to be just root, but as of now that's reserved for your Javascript source files as opposed to actual compiled files. Example:
assets.js.root = "/js/src"
assets.js.build = "/js/build/prod"
❗ Make sure that je new js build path is also updated in the gulpfile!
That's it! You're done. ☕
Garp moved to a Composer package.
This changes Garp a lot in that it has be able to stand on its own when tested for instance. A lot of unit tests broke because they relied on Garp being part of a bigger project. These tests have been moved out of Garp (conceptually you could say they're integration tests) and into a Garp sandbox project.
Make sure you update Golem before updating Garp!
To migrate to Garp composer version, see the accompanying wiki article.
That should be your step 1 in upgrading. Just make sure you require ^3.8.0. Run composer update to install.
❗ Look into this issue if you're getting empty Composer packages on your web server (most often noted by an error stating Zend_Registry cannot be found when deploying).
Secondly:
- Update
composer.jsonin the host project to autoload its ownApp_andModel_namespaces.
"autoload": {
"psr-0": {
"App_": "library/",
"Golem_": "library/",
"Model_": "application/modules/default/"
}
}
Garp_Loader is deprecated in favor of Composer's autoloader.
- Create
tests/TestHelper.php
<?php
date_default_timezone_set('Europe/Amsterdam');
define('APPLICATION_ENV', 'testing');
define('BASE_PATH', realpath(dirname(__FILE__) . '/..'));
error_reporting(-1);
ini_set('log_errors', 0);
ini_set('display_startup_errors', 1);
ini_set('display_errors', 'stderr');
$garpRoot = BASE_PATH . '/vendor/grrr-amsterdam/garp3';
require_once $garpRoot . '/application/init.php';
$application = new Garp_Application(
APPLICATION_ENV,
APPLICATION_PATH . '/configs/application.ini'
);
$application->bootstrap();
Zend_Registry::set('application', $application);
$mem = new Garp_Util_Memory();
$mem->useHighMemory();- If you're not already loading
vendor/autoload.phpin yourindex.php, make sure you do:
// file: public/index.php
require_once('../vendor/autoload.php');- Rename
application/modules/default/modelstoapplication/modules/default/Model(to supportpsr-0style autoloading). - Run
g models migrateGarpModels. Garp models have moved from theG_Model_namespace to theGarp_Model_Db_namespace. Make sure your project doesn't reference the former still. It's possible yourAuthLocalmodel is not correctly configured to extend from Garp. Make sure"module": "garp"is inAuthLocal.jsonand its extended model extends fromGarp_Model_Db_AuthLocal. - You can remove
library/PHPExcelandlibrary/Zend: they're required by Composer.
Alle tabellen worden vanaf deze versie in lowercase gegenereerd. Het is dus zaak het volgende stappenplan aan te houden:
- hernoem je tabellen naar de lowercase variant. (volledig lowercase,
_MovieGenrewordt dus_moviegenre) - draai
g spawn - herschrijf alle referenties naar de oude tabelnamen. In Ack kun je de volgende query gebruiken:
[ `\'\(]+Cinema[ `\'\.]+om ze te vinden.
Optioneel: je kunt in app.ini de parameter app.domain vullen, voor FullUrl helpers e.d.
(ik weet niet zeker of we dit 3.6 noemen!)
@harmenjanssen (12-12-2012)
- cms.css is verplaatst naar Sass, d.w.z. dat de echte CSS file dus in
/public/css/compiledstaat. In het CMS wordt dit pad gebruikt. Mocht je nou geen icoontjes zien bij de datatypes kijk dan even of deze file wel goed geladen wordt. - er is een partial bijgekomen:
cms-stylesheets.phtml. Hierin kun je app-specifieke stylesheets kwijt. Bovenstaande cms.css wordt daar ook in gezet. Met de komende WYSIWYG editor is dat heel handig omdat je nog wel wat custom styles zou moeten kunnen toevoegen (zoals een @font-face dingetje van Google of Typekit). Als deze partial er niet is krijg je logischerwijs een dikke error.
svn.grrr.nl/garp3/code/branches/3_5
Toevoegen aan core.ini:
store.type = "Cookie"
Let op! Modellen die afstammen van een Garp model afstammen moeten iets anders inheriten dan het geval was:
Model_Image > G_Model_Image > Model_Base_Image
in plaats van:
Model_Image > Model_Base_Image > G_Model_Image
Je zult dus je app-specifieke modellen aan moeten passen.
@davidspreekmeester public/css/cms-icons.css heet nu public/css/cms.css
@harmenjanssen We hanteren een nieuwe syntax voor auth variabelen, specifiek voor het auth.login._ en auth.login.register._ stukje. In de scaffoldversie van application.ini kun je het juiste formaat al vinden. Voorbeeld:
auth.login.view = “login.phtml”
@harmenjanssen We zijn van auth_facebook en auth_local en auth_twitter enzovoorts gegaan naar de Garp 3.4 nieuwe stijl namen AuthFacebook, AuthLocal, AuthTwitter etc.
@davidspreekmeester
Waar een homofiele relatietabel zoals _UserUser voorheen de kolommen user_id1 en user_id2 zou hebben, gebruiken we vanaf 3.5 user1_id en user2_id.
@davidspreekmeester
Voorheen hadden we het bestand _HabtmRelations.json, waar alle hasAndBelongsToMany relaties in gedefinieerd worden. Vanaf 3.5 dienen deze relaties in de configuratie van het eerste model in de relatie (alfabetisch gezien) te gebeuren. De configuratie is hetzelfde als voor andere typen relaties, maar dan met type: hasAndBelongsToMany. Zie de Spawner docs voor uitgebreidere info.
@harmenjanssen Omdat de virtuele kolom Author ook al wordt toegevoegd in de joint view. Pas bij bestaande data eerst de kolom in de database aan (zodat je geen data kwijt raakt). Pas daarna de Spawn config aan en draai een Spawn.
@harmenjanssen Pas het volgende aan in application.ini:
-resources.layout.layoutPath = APPLICATION_PATH "/modules/default/views/layouts"
+resources.layout =
+resources.frontController.plugins.LayoutBroker = "Garp_Controller_Plugin_LayoutBroker"
-resources.frontController.moduleDirectory = APPLICATION_PATH "/modules"
+resources.frontController.moduleDirectory[] = APPLICATION_PATH "/modules"
+resources.frontController.moduleDirectory[] = APPLICATION_PATH "/../garp/application/modules"
De symlink "g" in APPLICATION_PATH "/modules" moet vanaf nu wijzen naar garp/application/modules/g.
svn.grrr.nl/garp3/code/branches/3_4
@peter Geen support meer voor xtype = ‘compositefield’. Gebruik nu xtype = ‘fieldset’ met layout = ‘hbox’ om visueel de zelfde rendering te verkrijgen.
@davidspreekmeester De aanroep in models.phtml is veranderd. Dit bestand wordt nu nog maar gedeeltelijk gespawnd. Er moeten wat Ext aanroepen voor en na de gespawnde aanroepen. Zie
garp/scripts/scaffold/application/modules/default/views/scripts/partials/models.phtml
voor de juiste syntax. Dit kun je gebruiken als inhoud voor models.phtml in de applicatie, een Spawn-sessie daarna zal de rest aanvullen.
svn.grrr.nl/garp3/code/branches/3_3 revision 3357 25 november 2011
@harmenjanssen Alle modellen moeten in acl.ini genoemd worden zodat ze in ACL bekend worden en door de Content Manager gebruikt worden. Als ze er niet instaan kun je ze niet editen in het CMS. Bijvoorbeeld: (bij resources) acl.resources.G_Model_Video.id = "G_Model_Video" acl.resources.Model_BlogPost.id = "Model_BlogPost" En dan ook nog: (bij permissions) acl.resources.G_Model_Video.allow.all.roles = "admin" acl.resources.Model_BlogPost.allow.all.roles = "admin" Zie n8.nl voor een recente implementatie.
@harmenjanssen application/configs/cache.ini moet aanwezig zijn. Hoeft niet per sé gevuld te zijn, maar er moeten wel entries voor production / staging / development in staan . Zie n8_garp3 repository voor een voorbeeld van de daadwerkelijke implementatie.
revision ? datum? Asset version @harmenjanssen In public/.htaccess dient:
RewriteRule ^([0-9]+)/(css|js|media)/(.*) $2/$3 [L]vervangen te worden door:RewriteRule ^(\d+)/(css|js|media)/(.*) $2/$3 [L]
revision 2684 20 september 2011 Image / storage refactor @davidspreekmeester Snippet.image is een veld met een filename, dit moet Snippet.image_id worden, die verwijst naar een image record. De entries voor cdn in application.ini zijn veranderd. De benodigde entries zijn:
cdn.type = 'local'
cdn.domain = HTTP_HOST
;cdn.type = 's3'
;cdn.domain = "grrr.nl.s3.amazonaws.com"
cdn.extensions = "jpg,jpeg,gif,png,zip,pdf,xls,xlsx,csv"
cdn.path.upload.image = "/uploads/images"
cdn.path.upload.document = "/uploads/documents"
cdn.path.static.image = "/2011/media/images"
cdn.path.static.document = "/2011/documents"
;cdn.s3.apikey = "XXXXXX"
;cdn.s3.secret = "XXXXXX"
;cdn.s3.bucket = "grrr.nl"
De volgende entries voor de setup van images in application.ini kunnen verwijderd worden:
image.uri.scaled = '/uploads/images/scaled/'
image.uri.upload = '/uploads/images/'
image.path.upload = APPLICATION_PATH "/../public/uploads/images/"
image.path.scaled = APPLICATION_PATH "/../public/uploads/images/scaled/"
image.host.static = "http://" HTTP_HOST
In plaats van CDN moet in Javascript IMAGES_CDN en DOCUMENTS_CDN gezet zijn.