Upgrading from 0.7.0 to 0.8.0¶
Upgrade composer.json
¶
In your composer.json
file, upgrade the version of netgen/block-manager
package to ~0.8.0
and run the composer update
command.
Note
If you have Netgen Layouts installed on eZ Platform, the package name will
be netgen/block-manager-ezpublish
.
Note
Integrations into Netgen Admin UI and eZ Platform UI also have separate
packages whose versions need to be bumped to ~0.8.0
.
Activate required bundles¶
Version 0.8 requires FOS HTTP Cache Bundle to be activated, so if not already
present, activate FOS\HttpCacheBundle\FOSHttpCacheBundle
in your kernel.
Database migration¶
Run the following command from the root of your installation to execute migration to version 0.8 of Netgen Layouts:
$ php bin/console doctrine:migrations:migrate --configuration=vendor/netgen/block-manager/migrations/doctrine.yml
Upgrading Netgen Content Browser¶
Netgen Content Browser version 0.8 was also automatically installed. Be sure to read its upgrade instructions too, to make sure you custom code keeps working.
Updates to Varnish VCL¶
To enable caching and later cache clearing of block and layout HTTP caches, you
will need to use Varnish. To make the cache clearing work, you need to modify
your Varnish VCL and add the following rules somewhere in your vcl_recv
function. If you’re using eZ Platform and the VCL supplied by it, the best place
to put this is in ez_purge
function (which is called from vcl_recv
),
right after if (req.http.X-Location-Id) { ... }
block.
For Varnish 3:
if (req.http.X-Layout-Id) {
ban( "obj.http.X-Layout-Id ~ " + req.http.X-Layout-Id);
if (client.ip ~ debuggers) {
set req.http.X-Debug = "Ban done for layout with ID " + req.http.X-Layout-Id;
}
error 200 "Banned";
}
if (req.http.X-Block-Id) {
ban( "obj.http.X-Block-Id ~ " + req.http.X-Block-Id);
if (client.ip ~ debuggers) {
set req.http.X-Debug = "Ban done for block with ID " + req.http.X-Block-Id;
}
error 200 "Banned";
}
For Varnish 4 and later:
if (req.http.X-Layout-Id) {
ban("obj.http.X-Layout-Id ~ " + req.http.X-Layout-Id);
if (client.ip ~ debuggers) {
set req.http.X-Debug = "Ban done for layout with ID " + req.http.X-Layout-Id;
}
return (synth(200, "Banned"));
}
if (req.http.X-Block-Id) {
ban("obj.http.X-Block-Id ~ " + req.http.X-Block-Id);
if (client.ip ~ debuggers) {
set req.http.X-Debug = "Ban done for block with ID " + req.http.X-Block-Id;
}
return (synth(200, "Banned"));
}
Breaking changes¶
The following breaking changes were made in version 0.8 of Netgen Layouts. Follow the instructions to upgrade your code to this newer version.
Some classes and interfaces had their namespaces changed. Update your custom code working with these classes and interfaces. The following table lists the old and the new interface and class names:
Old FQCN
New FQCN
Netgen\BlockManager\API\Values\Page\Block
Netgen\BlockManager\API\Values\Block\Block
Netgen\BlockManager\API\Values\Page\Placeholder
Netgen\BlockManager\API\Values\Block\Placeholder
Netgen\BlockManager\API\Values\Page\CollectionReference
Netgen\BlockManager\API\Values\Block\CollectionReference
Netgen\BlockManager\API\Values\Page\BlockCreateStruct
Netgen\BlockManager\API\Values\Block\BlockCreateStruct
Netgen\BlockManager\API\Values\Page\BlockUpdateStruct
Netgen\BlockManager\API\Values\Block\BlockUpdateStruct
Netgen\BlockManager\API\Values\Page\Layout
Netgen\BlockManager\API\Values\Layout\Layout
Netgen\BlockManager\API\Values\Page\Zone
Netgen\BlockManager\API\Values\Layout\Zone
Netgen\BlockManager\API\Values\Page\LayoutCreateStruct
Netgen\BlockManager\API\Values\Layout\LayoutCreateStruct
Netgen\BlockManager\API\Values\Page\LayoutUpdateStruct
Netgen\BlockManager\API\Values\Layout\LayoutUpdateStruct
Notable change is the
Block
interface since it’s used inNetgen\BlockManager\Block\BlockDefinition\BlockDefinitionHandlerInterface::getDynamicParameters
. method. You will need to modify your custom block definition handlers to use the new interface.In
Netgen\BlockManager\Block\BlockDefinition\BlockDefinitionHandlerInterface::getDynamicParameters
method, a second, unused, parameter called$parameters
was removed from the interface. Remove it from your custom block definition handlers.A new method called
isContextual
was added toNetgen\BlockManager\Collection\QueryType\QueryTypeHandlerInterface
interface. The purpose of this method is to signal to the system when the query acts as a contextual query, i.e., if it depends on data from current page to run. You need to add this method to your custom query type handlers.The following is the method signature as well as an example implementation:
/** * Returns if the provided query is dependent on a context, i.e. currently displayed page. * * @param \Netgen\BlockManager\API\Values\Collection\Query $query * * @return bool */ public function isContextual(Query $query);
public function isContextual(Query $query) { return $query->getParameter('use_current_location')->getValue() === true; }
BlockDefinitionHandlerInterface::hasCollection
method has been removed. From now on, specifying that the block has a collection is done through configuration. The following shows the old and new way of specifying that the block has a collection:// Old way <?php namespace MyApp\Block\BlockDefinition\Handler; use Netgen\BlockManager\Block\BlockDefinition\BlockDefinitionHandler; class MyBlockHandler extends BlockDefinitionHandler { /** * Returns if this block definition should have a collection. * * @return bool */ public function hasCollection() { return true; } }
# New way netgen_block_manager: block_definitions: my_block: collections: ~
Netgen\BlockManager\Layout\Resolver\TargetTypeInterface::provideValue
method has a changed signature. From now on, SymfonyRequest
object is provided as a parameter to the method, so there’s no need to manually fetch the current request from the request stack. The new interface looks like this:/** * Provides the value for the target to be used in matching process. * * @param \Symfony\Component\HttpFoundation\Request $request * * @return mixed */ public function provideValue(Request $request);
Netgen\BlockManager\Layout\Resolver\ConditionTypeInterface::matches
method has a changed signature. From now on, SymfonyRequest
object is provided as a first parameter to the method, so there’s no need to manually fetch the current request from the request stack. The new interface looks like this:/** * Returns if this request matches the provided value. * * @param \Symfony\Component\HttpFoundation\Request $request * @param mixed $value * * @return bool */ public function matches(Request $request, $value);
Netgen\BlockManager\Traits\RequestStackAwareTrait
trait has been removed. Inject the request stack service directly into the constructor.If using Netgen Layouts with eZ Publish 5, instead of redefining the alias for the content provider service, you now have to redefine the alias for newly introduced content extractor service.
# Before netgen_block_manager.ezpublish.content_provider: alias: netgen_block_manager.ezpublish.content_provider.ez5_request
# After netgen_block_manager.ezpublish.content_extractor: alias: netgen_block_manager.ezpublish.content_extractor.ez5_request
netgen_block_manager.google_maps_api_key
configuration was renamed tonetgen_block_manager.api_keys.google_maps
. The following shows an example of the old and new configs:# Old config netgen_block_manager: google_maps_api_key: MY_API_KEY
# New config netgen_block_manager: api_keys: google_maps: MY_API_KEY
standard
item view type is always added to all view types automatically. However, this was not true for view types that specified custom item view types. You had to specifystandard
item view type manually if you wanted to use it. From now on,standard
item view type will be added in those cases too. If you wish to disable it, you can do so like this:netgen_block_manager: block_definitions: my_block: view_types: my_view_type: item_view_types: standard: enabled: false
User policies are introduced. To be able to manage user policies in legacy administration interface of eZ Platform, you need to activate the provided
nglayouts
legacy extension. If you’re using eZ Platform UI, policy management is available automatically.Custom items can now be added to blocks manually, instead of just being able to return them from query types. Make sure to implement the
Netgen\BlockManager\Item\ValueLoaderInterface
for your custom items, as well as Content Browser backend, and then activate the value type in configuration:netgen_block_manager: value_types: my_value_type: name: 'My value type'