A documentation change is requested elsewhere. For Drupal core (and possibly other projects), once the change has been committed, this status should be recorded in a change record node.
I'm writing the 3rd edition of Pro Drupal Development and left the files chapter for one of the last ones to write based on the lack of information on the new structure of the APIs. After a lot of digging through core and modules - I've found the answer to some of the questions. Here's an example of writing a text string to a new file in the default public directory (in my case sites/default/files).
The $dest variable must contain a valid stream wrapper URI. The example above utilizes the file_build_uri function to create a valid stream wrapper URI that points to the destination directory which in this case the default public files directory. That's a fundamental change in D7 -- the use of stream wrapper uri's.
As soon as I have the chapter completed I'll post more information about what I found and how things work. Lots of changes.
My personal lessons learned is to always go and search for things in core. They may not be documented very well or documented at all - but with a little fundamental knowledge of how Drupal works you can usually find an example in core.
Yikes. Taking not of this, as a few of my modules use the file handling api extensively, and I'm going to have to rework a lot - thanks, rfay, for your docs!
Comments
Comment #1
xslim commentedsame for file_check_directory()
Comment #2
xslim commentedMaybe this function dose the work?
file_prepare_directory(&$directory, $options = FILE_MODIFY_PERMISSIONS)
with option FILE_CREATE_DIRECTORY
Comment #3
dave reidThis is critical to get documented on the module upgrade page.
Comment #4
catchThat's why we have #653068: Update documentation is incomplete.
Comment #5
joachim commentedTagging with Needs documentation so this shows up on that issue's list.
Comment #6
naught101 commentedSubscribing
Anyone figure out what the replacement is yet?
Comment #7
naught101 commentedThis change was introduced in CVS here: http://drupalcode.org/viewvc/drupal/drupal/includes/file.inc?r1=1.181&r2...
The patch was from #517814: File API Stream Wrapper Conversion
I have no idea what a "Stream wrapper" is yet, so I still don't know how to fix this..
Comment #8
naught101 commentedIn fact, I think this issue is a duplicate of #517814: File API Stream Wrapper Conversion.
Comment #9
rfayopened #872622: Stream Wrappers really, really need documentation and examples
Comment #10
toddtomlinson commentedI'm writing the 3rd edition of Pro Drupal Development and left the files chapter for one of the last ones to write based on the lack of information on the new structure of the APIs. After a lot of digging through core and modules - I've found the answer to some of the questions. Here's an example of writing a text string to a new file in the default public directory (in my case sites/default/files).
[code starts here]
<?php
$filename = 'testfile.txt';
$dest = file_build_uri($filename);
file_save_data('My data', $dest, FILE_EXISTS_REPLACE);
[code ends here]
The $dest variable must contain a valid stream wrapper URI. The example above utilizes the file_build_uri function to create a valid stream wrapper URI that points to the destination directory which in this case the default public files directory. That's a fundamental change in D7 -- the use of stream wrapper uri's.
As soon as I have the chapter completed I'll post more information about what I found and how things work. Lots of changes.
My personal lessons learned is to always go and search for things in core. They may not be documented very well or documented at all - but with a little fundamental knowledge of how Drupal works you can usually find an example in core.
I'll post more in the next day or so.
Comment #11
rfayI'm writing documentation this weekend and next week as well.
Also, am in the process of completing a File Example for the Examples project, which includes both File API usage and a mostly complete (read/write) stream wrapper implementation:
#874364: Create a file example demonstrating key file APIs and the streamwrapper concept
Would appreciate any reviews there.
@toddtomlinson, thanks for the post, and anything more you can add will be much appreciated.
The handbook docs pages will go at http://drupal.org/node/555118
Comment #12
rfayAdded http://drupal.org/node/877212 and http://drupal.org/node/877214. More work still to do.
Comment #13
rfayI've attempted to provide docs about this mystery:
module upgrade guide
A dedicated File API upgrade page
A new file example for Examples Project (See also http://api.drupal.org/api/drupal/developer--examples--file_example--file... in api.drupal.org)
Your review and improvement on those is welcome
Comment #14
geerlingguy commentedYikes. Taking not of this, as a few of my modules use the file handling api extensively, and I'm going to have to rework a lot - thanks, rfay, for your docs!