Message-ID: <766810322.3464.1485853296689.JavaMail.confluence@ip-10-127-227-164> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_3463_493079483.1485853296689" ------=_Part_3463_493079483.1485853296689 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Upgrading from 5.1 to 5.3

Upgrading from 5.1 to 5.3

=20 =20

This section describes how to upgrade your existing eZ Publish 5.1 i= nstallation to version 5.3. Make sure that you have a working backup of the= site before you do the actual upgrade, and make sure that the installation= you are performing the upgrade on is offline.

Note on Paths

Check for requirement= s

PHP 5.3.3 and higher is needed. Further information regarding System Req= uirements can be found on Requirements Doc= umentation Page.

Upgrade steps

Step 1: = Upgrade the distribution files

The easiest way to upgrade the distribution files is to unpack eZ Publis= h 5.3 to a separate directory and then copy the directories that contain si= te-specific files from the existing 5.1 installation into "/<ezp5-ro= ot>/". Make sure you copy the following directories:

NB: Since writable directories and files have = been replaced / copied, their permissions might have changed. You may have = to reconfigure webserver user permissions on specific folders as explained = in the file permissions chapter= of the installation process.

opcode cache

If you use APC, or an op-code cache solution, make sure to clear the cac= he. The easiest way is to restart your web server.

Step 2: upgr= ade custom extensions

If you are using custom extensions, the sub-directories inside the "exte= nsion" directory will also have to be copied from the existing 5.1 installa= tion into "/<ezp5-root>/ezpublish_legacy/extension/". Howeve= r, make sure that you do not overwrite any extensions that are included in = eZ Publish distribution, which currently are (Note: As of eZ Publish 5.2, these extensions have the same version number= as eZ Publish):

Note that upgrading the distribution files will overwrite the autoload a= rrays for extensions. You will need to re-generate the autoload arrays for = active extensions later.

Important: If you plan to upgrade your eZ Webs= ite Interface, eZ Flow or eZ Demo site package as well, then additiona= l extensions will be updated and the step for re-generate the aut= oload arrays can be skipped until that is done (links to documentation for = upgrading these site packages can be found in the last step of this page).<= /em>

Step 3: upgrade t= he database

This step assumes use of the built in database drivers, mysql (incl mari= adb) and PostgreSQL, for other databases supported via extension please use= scripts and documentation provided by extension.

For upgrading the database, you have to jump from 5.1 to 5.2 and then fr= om 5.2 to 5.3.

Import to your database the changes provided in :

/<ezp5-root>/ezpublish_l=
egacy/update/database/<mysql|postgresql>/5.2/dbupdate-5.1.0-to-5.2.0.=
sql
/<ezp5-root>/ezpublish_l=
egacy/update/database/<mysql|postgresql>/5.3/dbupdate-5.2.0-to-5.3.0.=
sql

  • Define a Doc= trine connection

    MySQL settings : ezpublish.yml or config.yml
    =20 
    doctrine:
    dbal:
        connections:
            my_connection:
                driver:   pdo_mysql
                host:     localhost
                port:     3306
                dbname:   my_database
                user:     my_user
                password: my_password
                charset:  UTF8
    =20
    =20
    =20 PostGreSQL : ezpublish.yml or config.yml =20  Expand source= =20
    =20
    =20 
    doctrine:
    dbal:
        connections:
            my_connection:
                driver:   pdo_pgsql
                host:     localhost
                port:     5432
                dbname:   my_database
                user:     my_user
                password: my_password
                charset:  UTF8
    =20
    =20

    Pro Tip

    Set your base DB params in your=20 parameters.yml/ parameters.yml.dist and refer them here.
    parameters.yml
    =20 
    parameters:
   database_driver: pdo_mysql
   database_host: localhost
   database_port: 3306
   database_name: ezdemo
   database_user: my_user
   database_password: my_password
   database_charset: UTF8
    =20
    ezpublish.yml / config.yml
    =20 
    doctrine:
   dbal:
       connections:
           my_connection:
               driver:   %database_driver%
               host:     %database_host%
               port:     %database_port%
               dbname:   %database_name%
               user:     %database_user%
               password: %database_password%
               charset:  %database_charset%
    =20

  • Define = one or several repositories

    ezpublish.yml
    =20 
    ezpublish:
  repositories:
      main: { engine: legacy, connection: my_connection }
    =20

  • (Optional) Make your SiteAccess config point to the r= ight repository

    =20
    =20 ezpublish.yml=20  Expand source= =20
    =20
    =20 
    ezpublish:
  system:
      my_siteaccess_group:
          repository: main
    =20
    =20

     

     

    Remove the old connection information

    Note : to benefit from the new configuration, don't forget to remove the= old configuration

    Old database access to remove
    =20 
    ezpublish:
    system:
        my_siteaccess_group:
            database:
                type: mysql
                user: my_user
                password: my_password
                server: localhost
                database_name: ezdemo
    =20

Step 4: Apply 5.2 & 5.3 configuration changes

YAML files

Since default configuration files have been overwritten during step one,= the few additions to those files that were made in 5.3 need to be applied = manually to the configuration files. All of those changes are = additions, none of them replaces what you already have. For most o= f them, at least one, if not all hierarchy elements (monolog, handler, fram= ework, router...) will already be there. All you have to do is add the miss= ing bits in the existing configuration blocks.

In ezpublish/config/config_dev.yml, add the config= uration for the chromephp log handler:

=20 
monolog:
    handlers:
        chromephp:
            type: chromephp
            level: info
=20 
In ezpublish/config/config.yml, you need t=
o add a few default values for the framework
=20 
framework:
    router:
        resource: "%kernel.root_dir%/config/routing.yml"
        strict_requirements: %kernel.debug%
    trusted_proxies: ~    
    http_method_override: true
 
twig:    
    debug: %kernel.debug%
    strict_variables: %kernel.debug%
=20
Session name

ezpublish.system.<siteAccessName>.session_name has be= en deprecated for defining session name. You now need to use ezpublis= h.system.<siteAccessName>.session.name.

Before:

=20 
ezpublish:
    system:
        my_siteaccess:
            session_name: SomeSessionName
=20

After:

=20 
ezpublish:
    system:
        my_siteaccess:
            session:
                name: SomeSessionName
=20
Routing

In rout= ing_dev.yml, add the resource import for the SensioDistributionBun= dle webconfigurator routes:

=20 
_configurator:
    resource: "@SensioDistributionBundle/Resources/config/routing/webconfig=
urator.xml"
    prefix: /_configurator
=20 
 

In routing.yml, add new login routes and the _ezpublishRestOptionsRoutes route loader:

 
=20 
_ezpublishRestOptionsRoutes:
    resource: "@EzPublishRestBundle/Resources/config/routing.yml"
    prefix: %ezpublish_rest.path_prefix%
    type: rest_options
 
login:
    path:   /login
    defaults:  { _controller: ezpublish.security.controller:loginAction }
login_check:
    path:   /login_check
logout:
    path:   /logout
=20
 Securit= y
In ezpublish/config/security.yml= , add the following:
=20 
access_control:    
    - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channe=
l: https }
=20

And again in ezpu= blish/config/security.yml, under ezpublish_front firewall, update to fit the following (be sure to remove ez= publish: true):

=20 
security:
    firewalls:
        ezpublish_front:
            pattern: ^/
            anonymous: ~
            form_login:
                require_previous_session: false
            logout: ~
=20

 

If you have added anything to parameters.= yml, we suggest that you add your custom settings to parameter= s.yml.dist, so that the composer post-update script handles those, a= nd generates their values correctly.

Templat= es

In your templates, change your links pointing t= o /user/login and /user/logout to appropriate login / login_check / logout = routes:

Before
=20 
<a href=3D"{{ path( 'ez_legacy', {'module_uri': '/user/login'} )=
 }}">Login</a>
<form action=3D"{{ path( 'ez_legacy', {'module_uri': '/user/login'} ) }}=
" method=3D"post">
<a href=3D"{{ path( 'ez_legacy', {'module_uri': '/user/logout'} ) }}">=
;Logout</a>
=20
After
=20 
<a href=3D"{{ path( 'login' ) }}">Login</a>
<form action=3D"{{ path( 'login_check' ) }}" method=3D"post">
<a href=3D"{{ path( 'logout' ) }}">Logout</a>
=20
ezpublish/Ez= PublishKernel.php

It is not possible to just copy your old EzPublishKernel.php file over from the previous installation, since quite a few changes were = made to this file in this release. We suggest that you simply reflect in th= e new kernel file any changes you made in the previous version.

composer.json

If you had modified composer.json to add your own requireme= nts, you must re-apply those changes to the new version, and run composer update.

Varnish (if applicab= le)

Anonymous state of a user is not checked through presence of is_lo= gged_in cookie any more. Therefore, when using Varnish, you must cha= nge the following in your VCL file:

Before
=20 
# ez_user_hash sub-routine
if (req.http.Cookie !~ "is_logged_in=3D" ) {
    # User don't have "is_logged_in" cookie =3D> Set a hardcoded anonymo=
us hash
    set req.http.X-User-Hash =3D "38015b703d82206ebc01d17a39c727e5";
}
=20
After
=20 
# ez_user_hash sub-routine
if (req.http.Cookie !~ "eZSESSID" ) {
    # User don't have session cookie =3D> Set a hardcoded anonymous hash
    set req.http.X-User-Hash =3D "38015b703d82206ebc01d17a39c727e5";
}
=20

Step= 5: Update cluster data (if applicable)

If your installation uses the DFS cluster, you are affected by the = sp= lit DFS tables feature that was added in 5.2. You can also ch= eck the DFS setup documentation document on steps 3 and 4 for a= dditional details and usage examples about the newly introduced configurati= ons.

To use the feature, you need to update your DFS database structure. It w= on't affect existing data, and doesn't require particular measures. Import = the following file into yourcluster database (it should be di= fferent from your eZ Publish database):

/<ezp5-root>/ezpublish_l=
egacy/update/database/mysql/5.2/dbupdate-cluster-5.1.0-to-5.2.0.sql<=
/pre>

The split table feature stores cache and storage into two different tabl=
es. For now, your ezdfsfile table contains both cache and storage. Starting=
 from now, eZ Publish will use the newly created table, ezdfsfile_cache, to=
 store cache. Since the table  is empty, it will react as if there was=
 no cache, and work without any changes.


However, we recommend that you remove entries related to cache from your=
 ezdfsfile table. There are several options.


Option 1: unclusterize, clear data, and reclusterize


This method requires that you shutdown the website completely&n=
bsp;for a little while. It mainly applies to small/medium websites (up to a=
 couple thousand content objects).




May require a lot of disk space





Since this method will create a local copy of every storage file (not in=
cluding cache) from your NFS to the local server, this method may require a=
 large amount of disk space. You can get an estimate of the required space =
by running the following query on your cluster database:




=20

SELECT SUM(size) from ezdfsfile WHERE name LIKE 'var/ezdemo\_site/s=
torage/%';
=20





It will give you the total size of storage items, in bytes. Remember to =
escape _ in your vardir.






Use the following commands from your /<ezp5-root>/ezpubli=
sh_legacy/ folder:




=20

cd ezpublish_legacy
bin/php/clusterize.php -u
=20





Next, truncate the ezdfsfile table fro=
m your database:




=20

TRUNCATE TABLE ezdfsfile
=20





And finally, re-create cluster data based on local data:




=20

cd ezpublish_legacy
bin/php/clusterize.php
=20





Option 2: perform a background cleanup of the storage table


An upgrade script is provided that will let you cleanup  the ezdfsf=
ile table on a live website, even with a large cluster. It will delete a co=
nfigurable (by default 1000) batch of cache rows from ezdfsfile, and sleep =
(by default for 100 ms) between batches. Run the following from the legacy =
root:




=20

cd ezpublish_legacy
php update/common/scripts/5.2/cleanupdfscache.php -h
=20





The script can be interrupted and rest=
arted anytime without risks for the system. We strongly suggest, if you exe=
cute it on a live website, that you monitor your database server's performa=
nces, and increase the sleep delay and/or decrease the limit if the SQL ser=
ver's load is too high.


Step 6: Regenerate the autoload array for extensions


To regenerate the autoload array, execute the following script from the =
root of your eZ Publish Legacy directory:




=20

cd ezpublish_legacy
php bin/php/ezpgenerateautoloads.php --extension
=20





Step 7: Link assets


Assets from the various bundles need to be made available for the webser=
ver through the web/ document root.


The following commands will first symlink eZ Publish 5 assets in "Bundle=
s" and the second will symlink assets (design files like images, scripts an=
d css, and files in var folder)  from eZ Publish Legacy:




=20

php ezpublish/console assets:install --symlink
php ezpublish/console ezpublish:legacy:assets_install --symlink
php ezpublish/console assetic:dump --env=3Dprod
=20





Step 8: Update re=
write rules


There are two ways eZ Publish 5 can be installed, either the full instal=
l with both the new Symfony stack and the legacy stack, or legacy only.&nbs=
p;In latter case you only need to point your '4.7 like' rewrite rules to&nb=
sp;/<ezp5-root>/ezpublish_legacy/ and that's it. Otherw=
ise, update your virtual host according to the eZ Publish 5.2 rewrite rules on confluence and p=
oint your host configuration to /<ezp5-root>/web/.


Step 9: Clear the cac=
hes


Whenever an eZ Publish solution is upgraded, all caches must be cleared =
in a proper way. This should be done from within a system shell:
Navigat=
e into the new eZ Publish directory.Run the script using the following shel=
l command:cd /<ezp5-root>/ezpublish_legacy/php bin/php/ezcache.php --=
clear-all --purgePurging ensures that the caches are physically removed. Wh=
en the "--purge" parameter is not specified, the caches will be expired but=
 not removed.
Note: Sometimes the script is unable to clear all cache fi=
les because of restrictive file/directory permission settings. Make sure th=
at all cache files have been cleared by inspecting the contents of the vari=
ous cache sub-directories within the "var" directory (typically the "var/ca=
che/" and "var/<name_of_siteaccess>/cache/" directories). If there ar=
e any cache files left, you need to remove them manually.


Step=
 10: Upgrade Extensions (site package)


Next, depending on if you originally installed eZ Flow, eZ Webin or eZ D=
emo site, follow the steps mentioned in the eZ Webin, eZ Flow or eZ Demo upgrade documentatio=
n.


Minor Versions =
Update Warning


Please have in mind that, after the upgrade to a major version of eZ Pub=
lish, you will need to perform regular updates with composer.


Before any minor update with composer, please execute all require steps =
described in the 5.3.x U=
pdate Instructions.


 
------=_Part_3463_493079483.1485853296689--