README

yii2-files-catalog

Developer: waizabu.com

It is a virtual file system with access control lists.

I have replicated the main principles of *nix filesystem where any object is represented by an inode in the disk, and each inode have a different identity (directory, file, symlink). What you get is a virtual file system that can rely on any existing file system, thanks to the usage of FlySystem in a deep layer,

License

Free for NonCommercial use. Otherwise contact us for a commercial license.

Installation

This extension is distributed as a composer library. Run

composer require eseperio/yii2-files-catalog

Then run migration

php yii migrate/up --migrationPath=@vendor/eseperio/yii2-files-catalog/src/migrations

Add the module to your modules configuration

'modules' => [
     'filex' => [
            'class' => \eseperio\filescatalog\FilesCatalogModule::class,
            'salt' => 'yourrandomstringhere'
            'identityClass' => 'youridentity/classname',
            'administrators' => ['adminusername']
            // 'administratorPermissionName' => 'permissionname'
        ]
      ]

To manage access control list, add administrators to module configuration.

Versioning.

This module supports file versioning. You can set how much files must be kept. File versioning can be disabled via configuration

Access control

Inodes access control is performed by ACLs. Any inode must have a rule associated in order to give access to it. Access can be granted to a user id or a role.

To know more about access control, see access control docs

File sharing

This module also includes file sharing functionalities. A file can be shared via email and folders and files can be shared with other users via user_id param. There are specific views for that. To see "Shared with me" files, go into shared url Users can only share those files which they had write permissions. You can set your custom settings overriding AclHelper::canShare()

Customization

You can customize any element of the module by overriding the classes in container definitions. Gridview uses column classes, controller uses actions, and so on.

Usage

Actions available

There is a default controller with the following actions.

Action	Description
Index	Displays the contents of a given dir. Accepts param `uuid` to select which directory to show
View	Only for inodes of type `file`. If files is image or pdf, it displays on screen, otherwise downloads the file
Properties	Displays properties of the file or directory selected
Upload	Action to handle file uploads
NewFolder	Displays the "create directory" form
Rename	Allows renaming an inode
BulkDelete	Bulk deletion
BulkDownload	Download many files at the same time
RemoveAcl	Remove permissions from an Inode
BulkAcl	Bulk permissions attachment
inheritAcl	Copy all selected permissions to all children
bulk-download	Download multiple files as a zip file
shared	Shows all files shared with the current logged in user
unshare	Removes an existing share with a user
email	Sends a file via email to custom address

Configuration

Property	Description	Default
`maxFileSize`	int the maximum number of bytes required for the uploaded file. Defaults to null, meaning no limit. Note, the size limit is also affected by `upload_max_filesize` and `post_max_size` INI setting and the 'MAX_FILE_SIZE' hidden field value. See [[FileValidator::getSizeLimit()]] for details. @see https://secure.php.net/manual/en/ini.core.php#ini.upload-max-filesize @see https://secure.php.net/post-max-size @see FileValidator::getSizeLimit	null
`directory`	string This will be used as default directory where all files will be created. Set to false to use your default storage component	'filex'
`maxVersions`	int number of maximun versions of a files that can be kept.	4
`storage`	string name of the component responsible of handling files. Must comply with flysystem.	'storage'
`user`	string The user component. This is used on blameable behavior	'user'
`userIdAttribute`	string attribute of the user component	'id'
`userNameAttribute`	string user attribute that returns the name. Can be a anything valid for [[ArrayHelper::getValue()]]	'username'
`db`	string Name of the db component to use on data handling	'db'
`usePjax`	bool whether use pjax on main view	true
`inodeRealPathCallback`	** null	array
`allowOverwrite`	bool whether overwrite existing files. Remember this setting can be overrided in calls tu save	false
`prefix`	string the prefix to be used on urlGroup	'filex'
`urlRules`	array the url rules (routes)	'controller:[\w\-]+
`maxTreeDepthDisplay`	int the max amount of elements to display when using a tree view. Set to false to disable	4
`groupFilesByExt`	bool whether show icons grouped by extension	false
`displayAuthorNames`	bool whether display author names on views	true
`routePrefix`	string the prefix for the route part of every rule declared in [[rules]]. The prefix and the route will be separated with a slash. If this property is not set, it will take the value of [[prefix]].	"filesCatalog"
`realFileNamesSystem`	string which kind of name use on saving files. Defaults to FILENAMES_BY_ID. Files will be stored using its own id, so an attacker can not find a file based on their public uuid. If you want to preserve an easy way to find physical FILENAMES_BY_ID: File 1979 will become prefix	1
`browserInlineMimeTypes`	array list of the mimetypes that can be represented directly in browser with their corresponding tag
`enableACL`	bool whether enable access control list	true
`administrators`	List of roles or usernames that can manage acl	['admin']
`aclException`	Classname of the exception to be thrown when user can access an inode	`eseperio\filescatalog\exceptions\FilexAccessDeniedException`
`defaultACLmask`	Default value for access control crud mask when no one has been defined	4
`maxInlineFileSize`	Since this module relies on Flysystem, you can not have a direct link to the file, so in order to preview images or mp4 videos they are converted to base64. This number limits the maximun size allowed for a file to be embedded. int max inline file size in bytes. Defaults to 10Mb	10000000
`checkFilesIntegrity`	bool whether save file hashes in database and check integrity everytime a file is required. In large filesystems it can make the database grow significantly.	true
`allowVersioning`	bool whether allow multiple versions of a file.	true
`identityClass`	string the class name of the [[identity]] object.	null
`salt`	String to be used as hash salt on sensitive operations, like delete	null
`defaultInodePermissions`	list with default permissions for inodes	[AccessControl::ACTION_READ]
`secureHashParamName`	name of the parameter to be used when sending and receiving secure hash	fxsh
`secureHashAlgorithm`	which algorithm use for secure hash generation	SHA3-256
`newFolderIconclass`	css classname for the new folder icon	'glyphicon glyphicon-folder-open';
`propertiesIconClass`	css classname for the properties icon	glyphicon glyphicon-list-alt
`addFilesIconClass`	css classname for the new add files icon	glyphicon glyphicon-cloud-upload
`showBreadcrumbButtonLabels`	whether display labels in breadcrumb buttons	false
`itemsPerPage`	number of items per page	10
`rbacItems`	array	callable Array with the available permissions or roles available while managing inode permissions
`readOnlyMessage`	string	message to display in gridview as a name suffix when user has no write permissions.
`offsetParam`	string	param name to be used while transferring offset to view. Used on next-previoust buttons
`sortParam`	string	param name to be used while transferring sort to view
`enableEmailSharing`	whether allow users share a file via email	false
`emailFromAddress`	Address to be used when sharing fils via email	false
`maxFileSizeForEmailShare`	max allowed size for a file to be sent over email	5mb

Other

In order to improve privacy inodes use the uuid as public pk, but an integer as internal pk. Keep simple id private. When using data providers, remember use the one included within this module. This module use adjacency models concept to manage nesting. That requires extra queries to get parents or childrens, but is way more efficient than nested-set pattern on system that require a lot of nodes and writes

Important: when a inode of type file is created, model is stored and then file data is stored. If file data can not be
stored, model is deleted. This is done to avoid orphaned files. If you want to change this behavior, override
`File::afterSave()` method.
You can check whether a file has been deleted by checking `hasErrors()` method. If it returns true, you can check
`getErrors()` method to get the error message.

Testing

See testing docs

eseperio / yii2-files-catalog

Maintainers

Details