Message-ID: <1525368905.4242.1485861956431.JavaMail.confluence@ip-10-127-227-164> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_4241_1718384266.1485861956431" ------=_Part_4241_1718384266.1485861956431 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Development Guidelines

Development Guidelines

These are the development/coding guidelines for eZ Publish 5.x k= ernel, they are the same if you intend to write Bundles, hack on eZ Publish= itself or create new functionality for or on top of eZ Publish.

Intro

Like most development guidelines these aims to improve secu= rity, maintainability, performance and readability of our software. They fo= llow industry standards but sometimes extend them to cater specifically to = our needs for eZ Publish ecosystem. The next sections will cover all releva= nt technologies from a high level point of view.

HTTP

eZ Publish is a web software that is reached via HTTP in most cases, out= of the box in eZ Publish 5.x kernel this is specifically: web (usually HTM= L) or REST.

We aim to follow the lates= t stable HTTP specification, and industry best practice:

  • User file uploads
    • Should follow recommendations for "User input" to validate file name
    • Should place uploaded files in a non public folder to avoid access to e= xecute uploaded file or in case of assets white list the type
    • Should be appropriately limited in size to avoid DOS attacks on disk sp= ace, cpu usage by antivirus tool etc...
  • File downloads
    • Should not rely on user provided file path for non public files, instea= d use a synthetic id
  • Admin operations
    • May be placed on a different (sub)domain then the front end website to = avoid session stealing across front and backend.
  • Fully support being placed behind a reverse proxy like Varnish

    • REST

    For now see the living REST v2 specification in our git repository for furt= her details.

    UI

    eZ Publish is often used as a web content management software, so we alw= ays strive to use the HTML/CSS/EcmaScript specifications correctly, and kee= p new releases up to date on new revisions of those. We furthermore always = try to make sure our software gracefully degrades making sure it is useful = even on older or less capable web clients (browsers), the industry terms fo= r this approach are:

    All these terms in general recommends aiming for the minimum standard fi= rst, and enhance with additional features/styling if the client is capable = of doing so. In essence this allows eZ Publish to be "Mobile first" if the = design allows for it, which is recommended. But eZ Publish should always al= so be fully capable of having different sets of web presentations for diffe= rent devices using one or several sets of "SiteAccess" (see eZ Publish term= s) matching rules for the domain, port or URI, so any kind of device detect= ion can be used together with eZ Publish, making it fully possible to write= for instance WAP based websites a= nd interfaces on top of eZ Publish.

    WEB Forms/Ajax

    As stated in the HTTP section, all unsafe requests to the web server sho= uld have a CSRF token to protect against attacks; this includes web forms a= nd ajax requests that don't use the GET http method. As also stated in the = HTTP section and further defined in the PHP section, User input should alwa= ys be validated to avoid XSS issues.

    HTML/Templates

    All data that comes from backend and in return comes from user input sho= uld always be escaped, in case of Twig templates this done by default, but = in case of PHP templates, Ajax and other not Twig based output this must be= handled manually.

    Output escaping must be properly executed according to the desired forma= t, eg. javascript vs. html, but also taking into account the correct charac= ter set (see eg. output escaping fallacy when not specifying charset encodi= ng in htmlspecialchars)

    Admin

    Admin operations that can have a severe impact on the web applications s= hould require providing password and require it again after some time has g= one, normally 10 - 20 minutes, on all session based interfaces.

    <TODO: Add more coding guidelines for HTML (XHTML5), Javascript, CSS = and templates>

    PHP

    For now see our comprehensive coding standard & guidelines wiki page on github.

    Public API

    The PHP Public API provided in eZ Publish 5.1 is in most cases in charge= of checking permissions to data for you, but some API's are not documented= to throw UnauthorizedException, which means that it is the consumer of the= API's who is responsible for checking permissions. The following example s= hows how this is done in the case of loading users:

    loadUser()
    =20 
    // Get a user
$userId =3D (int)$params['id'];
$userService =3D $repository->getUserService();
$user =3D $userService->loadUser( $userId );

// Now check that current user has access to read this user
if ( !$repository->canUser( 'content', 'read', $user ) )
{
    // Generates message: User does not have access to 'content' 'read' wit=
h id '10'
    throw new \eZ\Publish\Core\Base\Exceptions\UnauthorizedException( 'cont=
ent', 'read', array( 'id' =3D> $userId ) );
}
    =20

    Command line

    Output must always be escaped when displaying data from the database.

    <TODO: Expand on how best practice is to handle user input in eZ Publ= ish 5 to avoid XSS issues>

    Data & Databases
    • Values coming from variables should always be appropriately quoted or b= inded in SQL statements
    • The sql statements used should never be created by hand with one versio= n per supported database, as this increases both the maintenance load and t= he chances for security-related problems
    • Usage of temporary tables is discouraged, as their behaviour is very di= fferent on different databases. Subselects should be prefererred (esp. sinc= e recent mysql versions have much better support for them)
    • Full table locking is discouraged

    <TODO: guidelines for how data should be stored for maximum portabili= ty (hint: XML & abstraction)>

    Sessions

    Transactions

    Limita= tions in the SQL dialect supported

    Striving to support Mysql 5, PostgreSQL xx and Oracle 10, the following = limitations apply:

     

    ------=_Part_4241_1718384266.1485861956431--