Comment attachments

Swarm supports attaching arbitrary files to comments in code reviews and jobs.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Comment attachment storage

To store files attached to comments, Swarm looks for a depot named //.swarm. As Swarm does not create this depot, you need to create it, or specify another depot that the Swarm admin user can write to.

The depot used to store Swarm attachments must be:

  • a classic depot (stream, unload, archive, and spec depots are not supported)
  • a local depot (remote depots are not supported)
  • a depot that the Swarm admin user can write to but other users cannot access. For more information about permissions, see Authorizing access in the Helix Core Server Administrator Guide.
    • Tip

    It is best practice to use a depot directory that is not used to store any other files, this stops other users having access to the attachments stored in the depot. We recommend that you use //.swarm

Create a directory for the comment attachments

We recommend that you use //.swarm because it is best practice to use a depot directory that is not used to store any other files This prevents other users from having direct access to the comment attachments.

  1. To create a //.swarm depot, run the following as a user with admin-level privileges:

    2. $ p4 depot .swarm

  2. Ensure that the Swarm admin user can write to the //.swarm depot and make sure that other users cannot access it.

    3. For information on creating depots, see Working with depots in Helix Core Server Administrator Guide.

Specify the location for the comment attachments

By default Swarm looks for a depot named //.swarm, to specify a different depot path for comment attachments, use the depot_storage configuration block in the SWARM_ROOT/data/config.php file.

Replace depot_name with the depot where comment attachments are stored. The Swarm admin needs to be able to write to this depot but make sure that other users cannot access it:

<?php
    // this block should be a peer of 'p4'
    'depot_storage' => array(
        'base_path'  => '//depot_name',
    ),
Tip

The base_path can be more than just the depot name, for example //depot/perforce/.swarm would work.

Maximum size of comment attachments

You can limit the size of comment attachments with the attachments configuration block in the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'attachments' => array(
        'max_file_size'  => 0, // the maximum file size to accept in bytes
    ),

Replace the 0 with the maximum file size in bytes that you want Swarm to accept for a comment attachment. If the file size is exceeded, users will see an error.

Note

Be aware that PHP's upload_max_filesize setting in SWARM_ROOT/public/.htaccess overrides max_file_size (which overrides the setting in PHP's php.ini). You can only use max_file_size to be more restrictive than the setting in SWARM_ROOT/public/.htaccess.

The default for upload_max_filesize is 8 MB (8 megabytes). Increase this limit if your commenters need to upload larger files.

You may also have to increase post_max_size. post_max_size should always be set larger or equal to upload_max_filesize, and Swarm's max_file_size should always be either unset, or set smaller or equal to upload_max_filesize, otherwise users will encounter unexpected rejection of their comment attachments.

See Handling file uploads: Common Pitfalls for more details.