Getting a File By ID
All File objects have a unique numerical ID. If you know the exact numerical ID of the page you want to work with, use this code:
$f = \File::getByID(1); // Retrieves the File object with an ID of 1.
Working with the File Object
Once you have a File object, there's a lot you can do with it. All methods on the Concrete\Core\File\File object are available to you, as well as all methods in the Concrete\Core\File\Version object. Every time you call a method on a File object, if the File class itself doesn't contain the method, the approved version of the File object will be retrieved, and that method will be run on it. For example, taking the $f File object above:
print $f->getFileID();
This retrieves "1" – by running the getFileID() method on the $f object itself.
print $f->getURL();
This retrieves http://www.example.com/1234/1234/1234/foo.txt – the URL of the file. The method getURL() doesn't exist on the \Concrete\Core\File\File object – it exists on the \Concrete\Core\File\Version object. The File object runs $this->getApprovedVersion() behind the scenes to retrieve the approved version of the File, and passes the method onto it.
Retrieving a Specific File Version
Most of the time you'll want to worry about the approved version of the File. After all, this is the version that has specifically been approved through the file manager (or, it's the most recent version if a specific approved version hasn't been selected.) Advanced applications might need more flexibility, however. If, for example, you know the approved version of the File isn't the most recent one, here's how you might work with them independently:
$approved = $f->getApprovedVersion(); // Retrieves the approved version of a File
$recent = $f->getRecentVersion(); // Retrieves the most recent version of a File
$specific = $f->getVersion(5); // Retrieves the version of the file with the specific version ID of 5.
$modify = $f->getVersionToModify(); // Returns a file version object that is to be written to. Computes whether we can use the current most recent version, OR a new one should be created
In all these cases, the returned object is an instance of a specific Concrete\Core\File\Version object. The API documentation details all of the methods available on this object.