CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

File uploading, file storage and CakePHPs MediaView class

This article includes how to upload and store files, because I've seen a lot of discussion about that too, but if you're just interested in how to use the MediaView class scroll down.

Handling file uploads in CakePHP

First let's start with the required form, to create a file upload form all you have to do is this:

echo $form->create('Media', array('action' => 'upload', 'type' => 'file'));
echo $form->file('file');
echo $form->submit(__('Upload', true));

 

The "type" in the options of Form::create() takes post, get or file. To configure the form for file uploading it has to be set to file which will render the form as a multipart/form-data form.

When you submit the form now, you'll get data like this in $this->data of your controller:

Array
(
[Media] => Array
(
[file] => Array
(
[name] => cake.jpg
[type] => image/jpeg
[tmp_name] => /tmp/hp1083.tmp
[error] => 0
[size] => 24530
)
)
)

Ok, now the big question with a simple answer is where the file data should be processed, guess where. Right – in the model because it's data to deal with and validation to do against it. Because it's a recurring task to upload files I suggest you to write a behaviour for it or convert your existing component to a behaviour.

If you keep it generic you can extend it with a CsvUpload, VideoUpload or ImageUpload behaviour to process the file directly after its upload or do special stuff with it, like resizing the image or parsing the csv file and store its data in a (associated) model.

We're not going to show you our own code here for obvious reasons, but I'll give you a few hints what you can or should do inside of the behavior:

  1. Validate the uploaded field, the field itself contains already an error code if something was wrong with the upload. Here is a link to the php manual page that shows you the list of the errors that you can get from the form data. http://www.php.net/manual/en/features.file-upload.errors.php
  2. Validate the uploaded file, is it really the kind of file you want and does it really contain the data structure you want?
  3. Check if the target destination of the file is writeable, create directories, whatever is needed and error handling for it, I suggest you to use CakePHP's File and Folder classes for that.
  4. Add a callback like beforeFileSave() and afterFileSave() to allow possible extending behaviors to use them.

Database vs file system storage

Feel free to skip that part if you already store the files in the file system.

Storing files in the database is in nearly all cases a bad solution because when you get the file it has to go its way through the database connection, which can, specially on servers that are not in the same network, cause performance problems.

Advantages of storage in the file system:

  1. Easy and direct file access, to parse them (csv, xml...) or manipulate them (images)
  2. You don't need to install any additional software to manage them
  3. Easy to move and mount on other machines
  4. Smaller then stored in a DB

The suggested solution is to store meta data of the file like size, hash, maybe path and other related info in a DB table and save the file in the file system.

Some people come up with the security and want to store a file because of that in the database which is wrong. You should not store the file in a public accessible directory like the webroot of the application. Store it in another location like APP/media. You control the access to the file by checking the permissions against the DB records of your meta data and sending it by using the CakePHP MediaView class, I'll explain later how to use it.

I don't say that storage of files inside the DB is in general a bad idea but for web based applications it is in nearly every case a bad idea.

File system Performance

A bottleneck in the long run on every file system is a large amount of files in a single directory. Imagine just 10.000 users and each has an individual avatar image. Further ext3 for example is limited to 32000 sub folders, other file systems have maybe similar restrictions. You can find a list of file system limitations here: http://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits

To avoid performance problems caused by that you should store your files in a pseudo-random directory structure like APP/media/32/a5/3n/. This will also allow you to easily mount some of the semi-random created directories on another machine in the case you run out of disk space.

/**
 * Builds a semi random path based on the id to avoid having thousands of files
 * or directories in one directory. This would result in a slowdown on most file systems.
 *
 * Works up to 5 level deep
 *
 * @see http://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits
 * @param mixed $string
 * @param integer $level
 * @return mixed
 * @access protected
 */
	protected function _randomPath($string, $level = 3) {
		if (!$string) {
			throw new Exception(__('First argument is not a string!', true));
		}

		$string = crc32($string);
		$decrement = 0;
		$path = null;
		
		for ($i = 0; $i < $level; $i++) {
			$decrement = $decrement -2;
			$path .= sprintf("%02d" . DS, substr('000000' . $string, $decrement, 2));
		}

		return $path;
	}

You should also know that php running in safe mode does not allow you to create more then one directory deep in one call. You have to take this in consideration, the above function does not cover that because safe mode is basically deprecated and will be also removed in php6

Sending a file to the client – or the unknown MediaView class

From what I've seen in the ruins of outsourced projects that asked us for rescue and also in the CakePHP googlegroup I think not many people are aware that CakePHP has a view that is thought to be used for downloads and display (images, text...) of files. It's called the MediaView class.

http://api.cakephp.org/class/media-view

I'll now explain you how to use this class to send files to the client.

/**
 * Sends a file to the client
 *
 * @param string $id UUID
 * @access public
 */
	public function download($id = null) {
		$this->Media->recursive = -1;
		$media = $this->Media->read(null, $id);

		if (empty($media)) {
		$this->redirect('/', 404, true);
		}
		
		$this->set('cache', '3 days');
		$this->set('download', true);
		$this->set('name', $media['Media']['slug']);
		$this->set('id', $media['Media']['filename']);
		$this->set('path', APP . 'media' . DS . $media['Media']['path']);
		$this->set('modified', $media['Media']['modified']);
		$this->set('mimeType', $media['Media']['mime_type']);
		$this->set('extension', $media['Media']['extension']);

		$this->view = 'Media';
		$this->autoLayout = false;
		if ($this->render() !== false) {
			$this->Media->updateAll(
				array('Media.downloads' => 'Media.downloads + 1'),
				array('Media.id' => $id));
		}
	}

You simply have to set autoLayout to false and the view class to media.

$this->view = 'Media';
$this->autoLayout = false;

There are a few view variables to set to “configure” the file download or display. To control if you want to make the client downloading the file or to display it, in the case of images for example, you simply set 'download' to true or false;

	$this->set('download', true);

You can control the browser caching of the file by setting cache. Please not that you do not have to use caching if download is set to true! Downloads do not need caching.

	$this->set('cache', '3 days');

The next part might be a little confusing, you have “id” and “name”. Id is the actual file on your server you want to send while name is the filename under which you want to send the file to the client. “path” is the path to the file on the server.

	$this->set('name', $media['Media']['slug']);
$this->set('id', $media['Media']['filename']);
$this->set('path', APP . 'media' . DS . $media['Media']['path']);

If you want to send a mime type that does not already in the MediaView class you can set it.

	$this->set('mimeType', $media['Media']['mime_type']);

If you don't set it, the class will try to determine the mime type by the extension.

	$this->set('extension', $media['Media']['extension']);

Note that you have to set the extension to make it work and that the extension is attached to the filename! If you store the filename with an extension you have to break it up.

When everything is set you can check if render() was successfully and do whatever you want after that, for example count the download.

	if ($this->render() !== false) {
	$this->Media->updateAll(
	array('Media.downloads' => 'Media.downloads + 1'),
	array('Media.id' => $id));
}

Closing words

I hope you enjoyed reading the article and it helped you improving your knowledge about CakePHP. Feel free to ask further questions by using the comment functionality. Have fun coding!

Latest articles

Navigation options for improved usability

Ease of navigation is closely linked to user experience - it can make or break how the user interacts with your website. From being able to find and use your navigation menu, through to the user being able to find the information they are looking for, it is important to ensure your navigation options are cleverly designed and stick to best practices.   If visitors are having difficulty with your navigation options, you are missing an opportunity to either create a conversion, delight your customer or engage a potential client.   When it comes to your website usability, here are some things you can focus on to ensure your site’s navigation is a user-friendly one:   1.     Keep it simple While this one may sound obvious, it is important to ensure that you avoid making your navigation difficult to comprehend. Examples of this include cluttered navigation menus, disorganized sub menus   2.     Keep it predictable While creativity makes your website stand out and is great to catch a user's attention and provoke emotion, it is important not to practise creativity in areas where predictability is preferred by the user or visitor. Such as when creating your navigation menu or the placement thereof.   3.     Keep it consistent It is key to keep the theme and structure of the different pages of your site consistent. Check our CakeDC.com menu and the different pages, each page keeps the overall theme and structure consistent. This is to ensure that your user is able to make sense of the content as quickly as possible when switching between pages.   4.     Have a clear hierarchical structure Every category and clickable sub category should have a clear hierarchical structure and should be visible in your menu. Doing this gives your user a clear view and pathway for them to go to the exact page or content that they are wanting. This point is particularly important for website that have a wide range of products or services.   5.    Make it distinct Navigation options should be clearly visible and easy to find. They should stand out from other graphics, images or backgrounds. This can be done through size, color and font.   6.    Link the logo to the homepage A good practice is to link the homepage to the logo of your company on your website. This logo should be in the same place on every page. Users have a high tendency to click on your logo, with the expectation that it will lead back to the home page as this is a generally predictable behavior across websites and design practices.   7.     Always include a search bar Search bars are necessary for making your website more usable to your visitors. Some visitors only want to find information by using a search bar within your site. Offer your users a way to navigate through your website without having to go through every page or menu option.

Difference between UX and UI

UX and UI are often misused in the tech industry. Understanding the key differences between UX and UI is beneficial, we take a quick look at both. UX, User Experience Design, and UI, User Interface Design, are both crucial to a product, such as a website, and work closely together while remaining vastly different disciplines. UX design tends to be more analytical and technical, while UI is not. A basic example for UX design would refer to how users interact with CakeDC.com, where they find the navigation menus (is this as per industry norm or do they have difficulty navigating around the website to find the information they are looking for, or how to contact CakeDC via our contact form or telephone number). Whereas UI design looks at ensuring brand relevance through the look and feel of the site, keeping color standards as per best practice. UX, User Experience Design UXD or User Experience Design refers to the process of enhancing the experience that a user has with a company, its products or its services. This is done by focusing on increasing the ease of use as well as improving the overall interaction between the user and the product or service. Good user experience design translates to customer satisfaction and loyalty so it's vitally important to ensure good design is put to practice! As a UX designer, you will  need to understand your site’s users and potential users, from creating persona’s to determining user stories and carrying out user testing. A persona could be an example of a customer who is seeking more information by contacting you versus a visitor who would like to learn more by reading your blog. UI, User Interface Design User Interface Design is the look, feel and interactivity of the product, basically referring to the means by which the user and a product (such as a website) interact with each other. The end goal of UI Design is to “achieve structure, analysis and optimization of a customer’s experience with the company and product.” UI Design includes activities that range from user guides and story lines through to UI prototyping and implementation with the development team.
  While there are differences between UX and UI, there are some similarities, let’s look at these:

  • Have a primary objective of improving customer satisfaction such as improving the use of a “contact us” form
  • Focus on the user and his/her interaction with a product/service such as having an easy to navigate menu
  • Can be applied to any product
Here is an example of the planning behind CakeDC.com

Website redesign? Here's a checklist of things you’ll need to consider

Redesigning your website can be a daunting and scary task, however, with the proper preparation and the right development team it can be a breeze! It can be a potentially long and tedious process, with a lot that can go wrong. From just a visual overhaul through to improving branding, user experience and sales, a website redesign can encompass a wide variety of changes that you can benefit from. Whatever your reasoning is for choosing a redesign, it offers you an opportunity to re-evaluate the bigger picture and see where improvements can be made. Here’s a quick checklist of things to look out for when embarking on a website redesign

  1. Strategy - why are you doing a redesign. Pencil down your main points behind the redesign project. What are your goals, ideals, visions. Where do you want the redesign to get you. What are the measurable results that you are hoping to see - importantly, you should also benchmark your current traffic and metrics.
  2. Saving your current assets - Have you made the proper back ups of the important files, media etc so that these remain accessible after the redesign of your website is complete. Go a step further, and take your metrics to work out what the most important assets and pages of your website - such product pages with the most sales or blog posts with the most views or social shares.
  3. Define your target audience - who is your idea visitor? Look at your customer journey and describe your customer.
  4. Have you checked out your competitors? Conduct competitive research - their overall look, problem areas, good ideas that appeal to you and your product/redesign.
  5. Outline your key features - identify what is most important to your website redesign. From shopping carts to news posts, landing pages, social sharing, security updates.
  6. Set your budget - outline what you want and how much you’d like to spend on it. Who - an agency, a freelancer etc - as well as the size or scope of your project, backend applications or additional features that you are looking for.
  7. Create a timeline and schedule your milestones - When do you expect to see things happen.
  8. Have you considered optimization? Don’t forget to make sure that your site is optimized social media and search engines.
  9. Test and revise - before launching!

We Bake with CakePHP