Document symfony events

[sharidas]

Based on the hooks available from : https://doc.owncloud.org/server/10.0/developer_manual/app/fundamentals/hooks.html

we have moved a bit further. Some of the hooks got replaced with symfony events.

[sharidas]

I will update the details about the events which got replaced here.

[PVince81]

@sharidas can you post the list of new hooks here as you touch them for future documentation ? Seems 10.0.8 will come with quite a lot. Not only the changed ones but also the very new ones like config hooks.

[settermjd]

ping @sharidas.

[sharidas]

The hooks present as of date in core are as follows:

• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L276 this hook will trigger before and after creating folder.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L352 this hook will trigger before and after removal of folder.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L584 this hook will trigger before event and after event when a file is read.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L639 this hook will trigger before event for file create.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L665 this hook will trigger before and after event for file update.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L723 this hook will trigger before and after event for file delete.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L767 this hook will trigger before and after event for file rename.
• https://github.com/owncloud/core/blob/master/lib/private/Files/View.php#L897 this hook will trigger before and after event for file copy.
• https://github.com/owncloud/core/blob/master/lib/private/Comments/Manager.php#L484 this hook will trigger before and after event for deleting comment.
• https://github.com/owncloud/core/blob/master/lib/private/Comments/Manager.php#L542 this hook will trigger before and after event for saving a comment.
• https://github.com/owncloud/core/blob/master/lib/private/Comments/Manager.php#L571 this hook will trigger before and after event for creating a comment.
• https://github.com/owncloud/core/blob/master/lib/private/Comments/Manager.php#L614 this hook will trigger before and after event for updating a comment.
• https://github.com/owncloud/core/blob/master/lib/private/User/User.php#L257 this hook will trigger before and after event for setting password for user.
• https://github.com/owncloud/core/blob/master/lib/private/User/Session.php#L485 this hook will trigger before and after event for user login.
• https://github.com/owncloud/core/blob/master/lib/private/User/Session.php#L846 this hook will trigger before and after event for user login.
• https://github.com/owncloud/core/blob/master/lib/private/User/Session.php#L915 this hook will trigger before and after event for user logout.
• https://github.com/owncloud/core/blob/master/lib/private/User/Manager.php#L324 this hook will trigger before and after event for creating a user.
• https://github.com/owncloud/core/blob/master/lib/private/User/Manager.php#L387 this hook will trigger before event for creating a user.
• https://github.com/owncloud/core/blob/master/lib/private/AppConfig.php#L153 this hook will trigger before and after event for setting appconfig values.
• https://github.com/owncloud/core/blob/master/lib/private/AppConfig.php#L218 this hook will trigger before and after event for deleting appconfig keys.
• https://github.com/owncloud/core/blob/master/lib/private/AppConfig.php#L246 this hook will trigger before and after event for deleting app.
• https://github.com/owncloud/core/blob/master/lib/private/Config.php#L150 this hook will trigger before and after event for setting or updating key value in config.php.
• https://github.com/owncloud/core/blob/master/lib/private/Config.php#L187 this hook will trigger before and after event for deleting key value in config.php

[PVince81]

is it up to date ? we also added group admins

[PVince81]

we should also list the new ones, not only the ones that replace old ones

[PVince81]

@sharidas I don't think you need to document where they are triggered but more about their names and their arguments, and semantically when they are triggered.

For example:

• "config_change", triggered before/after an app configuration change, arguments:
  • appId: app id
  • configKey: key
  • ...

If args different in before and after, might need to specify separately.

Then this can be put into a nice table later for the documentation.

There are likely many more new events to add, check the changelogs.

[sharidas]

Below is the detailed list of the symfony events triggered by the core:

• The column Event mapped to old event has
  • old event as ClassName::SignalName. For example OC_FileSystem::read.
  • If multiple old events are there then {ClassName::SignalName, ClassName::SignalName2}

Event Triggered	Event mapped to old event	When event is triggered	Arguments	Description about arguments
file.beforecreate/file.aftercreate	file.aftercreate -> OC_Filesystem::post_create	Folder is created	path	The path here would provide the absolute path
file.beforeCreate/file.afterCreate		Before file or after creation	run	The run is the current value of run. This variable can be reset by the listener
file.beforeUpdate/file.afterUpdate		Before or after file update	run	The run is the current value of run. This variable can be reset by the listener
file.beforeWrite/file.afterWrite		Before or after file being written	run	The run is the current value of run. This variable can be reset by the listener
file.beforedelete/file.afterdelete		Before or after deletion of folder	path	The path here would provide absolute path
file.beforeread/file.afterread	file.afterread -> OC_Filesystem::read	Before or after the file being read	path	The path here would provide absolute path
file.beforecreate/file.aftercreate	file.aftercreate -> OC_Filesystem::post_create	Triggered during post hook process	path	The path here would provide absolute path
file.beforeupdate/file.afterupdate	file.afterupdate -> OC_Filesystem::update	When the file is being updated	path	The path here would provide absolute path
file.beforedelete/file.afterdelete	file.afterdelete -> OC_Filesystem::delete	When the file is deleted	path	The path here would provide absolute path
file.beforerename/file.afterrename	file.afterrename -> OC_Filesystem::rename	When the file is renamed	oldpath, newpath	The oldpath, newpath here would provide absolute path
file.beforecopy/file.aftercopy	file.aftercopy -> OC_Filesystem::copy	When the file is copied	oldpath, newpath	The oldpath, newpath here would provide absolute path
comment.beforedelete		Before the comment is deleted	commentId	The commentId is the id associated with the comment
comment.afterdelete		After deleting the comment	commentId, objectId	The objectId isthe object id the comment is attached to
comment/beforesave/comment.aftersave		Before saving the comment before event is triggered. After saving comment after save is emitted.	objectId,commentId,message,status	The message is the message saved. status tells the listener whether the comment is created or updated.
comment.beforecreate/comment.aftercreate		These events are emitted when a new comment is added	objectId,message	The message is the message saved.
comment.beforeupdate/comment.afterupdate		These events are emitted when a comment is updated.	objectId,commentId,message	The message is the message saved.
user.beforesetpassword/user.aftersetpassword	user.beforesetpassword -> \OC\User::preSetPassword	These events are emitted when user password is called to set.	user,password,recoveryPassword	user is the user object. password is the password to set for the user. recoveryPassword is for the encryption app to reset encryption keys
user.beforelogin/user.afterlogin	user.beforelogin -> OC_User::pre_login, user.afterlogin -> OC_User::post_login	These events are emitted when user logins.	user,uid,password	user is the user object. password is the password for the user. uid is the user id.
user.beforelogout/user.afterlogout	user.beforelogout -> OC\User::preLogout, user.afterlogout -> OC\User::postLogout	These events are emitted when user logout from oC	uid	uid is empty. It helps to know if the logout action triggered
user.beforelogin	user.beforelogin -> OC\User::preLogin	Emitted when user logins with username and password	loginType,login,uid,_uid,password	loginType has hardcoded value password. It tells the type of login method. login and uid is the user id. _uid is going to be deprecated soon. Hence use login
user.afterlogin	user.afterlogin -> OC\User::postLogin	Emitted when user logins with username and password successfully	loginType,user,uid	loginType has hardcoded value password. It tells the type of login method. uid is the user id. user is the user object
user.beforelogin		Emitted when user logins with token	loginType,login,password	loginType has hardcoded value token. It tells the type of login method. login is the user id. password is the password for the user
user.afterlogin		Emitted when user logins with token successfully	loginType,user,login,password	loginType has hardcoded value token. It tells the type of login method. user is the user object. login is the user id. password is the password for the user
user.beforelogin		Emitted when user logins with apache backend successfully	loginType,login,password	loginType has hardcoded value apache. It tells the type of login method. login is the user id. password is empty
user.afterlogin		Emitted when user logins with apache backend successfully	loginType,user,login,password	loginType has hardcoded value apache. It tells the type of login method. user is the user object. login is the user id. password is empty
user.loginfailed		Triggered when user login is failed	user	user is the user id. It can also be null.
user.beforecreate		Triggered when user is created	uid	uid is the user id.
user.aftercreate		Triggered when user is created	uid, password	uid is the user id. password is the password for the user.
appconfig.beforesetvalue		Triggered when appconfig value is set	key, value, app	key, value and app are data to be stored in Db
appconfig.aftersetvalue		Triggered when appconfig value is set	key, value, app, update, oldvalue	key, value and app are data to be stored in Db. update is the updated value. oldvalue is the old value.
appconfig.beforedeletevalue		Triggered when appconfig key is deleted	app, key	key and app are data to be deleted from Db
appconfig.afterdeletevalue		Triggered when appconfig key is deleted	app, key	key, and app are data to be deleted from Db.
appconfig.beforedeleteapp		Triggered when app keys are deleted from appconfig	app	app are data to be deleted from Db
appconfig.afterdeleteapp		Triggered when app keys are deleted from appconfig	app	app are data to be deleted from Db.
config.beforesetvalue		Triggered when config key value is set	key, value	key and value are data to be stored in the config.php
``config.aftersetvalue`		Triggered when config key value is set	key, value, update, oldvalue	key and value are data to be stored in the config.php. update will let the listener know if the value is an update or not ( boolean value true/false), oldvalue is the previous value of the key
config.beforedeletevalue		Triggered when a key is deleted from config	key, value	key and value are data to be deleted in the config.php
config.afterdeletevalue		Triggered when a key is deleted from config	key, value	key and value are data to be deleted in the config.php.
share.beforeaccept		Triggered when the share is accepted	share	share is the share object to be updated.
share.beforereject		Triggered when the share is rejected	share	share is the share object to be updated.
share.afteraccept		Triggered when the share is accepted	share	share is the share object to be updated.
share.afterreject		Triggered when the share is rejected	share	share is the share object to be updated.
share.sendmail		Triggered when an email is sent for public link	link, to, cc, bcc	link is the public link created. to, cc and bcc are the recipients to recieve the email after creating the link
share.linkaccess		Triggered when a public link shared is accessed	shareObject, errorCode, errorMessage	shareObject is the link share.
file.beforecreate/file.aftercreate		Triggered when a file is created	path	path is the path of the file
file.beforeupdate/file.afterupdate		Triggered when a file is updated	path	path is the path of the file
user.beforefeaturechange/user.afterfeaturechange		Triggered when a user feature change is made, like user is made a group admin	user, feature, value, group	user user object. feature is hardcoded to groupAdmin. value is hardcoded to create. group is the group object
user.beforefeaturechange/user.afterfeaturechange		Triggered when a user is removed from as group admin	user, feature, value, group	user user object. feature is hardcoded to groupAdmin. value is hardcoded to remove. group is the group object
share.beforeCreate/share.afterCreate		Triggered when a share is created	shareData, shareObject	shareData is an array of share details. It could be preHook or postHook data. shareObject is the share object.
share.afterupdate	share.afterupdate -> {OCP\Share::post_update_permissions, OCP\Share::post_update_password, OCP\Share::post_set_expiration_date}	Triggered when a share is updated	shareobject, expirationdateupdated, oldexpirationdate, passwordupdate, permissionupdate, oldpermissions, path	shareobject is the share object. Remaining fields may be found based on the update happening with the share. For example passwordupdate could be found if a password update happens.
share.beforeDelete/share.afterDelete		Triggered when a share is deleted	shareData, shareObject	shareobject is the share object. shareData is the share details in an array
fromself.unshare		Triggered when the share is removed from the recipient user	shareRecipient, shareOwner, recipientPath, ownerPath, nodeType	shareRecipient is the recipient of the share. shareOwner is the owner of share who shared. recipientPath is the path of the share. nodeType is the type of the node

[PVince81]

in general I think the file name is irrelevant.

try thinking in terms of who will be using these events and what they want to know

[sharidas]

try thinking in terms of who will be using these events and what they want to know

Yes you are right, the file name doesn't make any sense. I have removed the column. So the columns on the updated https://github.com/owncloud/documentation/issues/3738#issuecomment-419377043 are
Method Name, Event Triggered, Arguments, Description.

Let me know if this looks ok? I am quite not sure if the app developer would be interested to know which method triggered this event. Because the developer would know what action was performed. So can I remove Method Name from the table? I would like to have your opinion here.

[PVince81]

the method name is irrelevant as well.

better have a description column that describes when each event is happening / in what context

[sharidas]

better have a description column that describes when each event is happening / in what context

Sure.

[sharidas]

Updated again with a new column which has the description about when the event is triggered https://github.com/owncloud/documentation/issues/3738#issuecomment-419377043

[sharidas]

Current state of the doc:

• Added a separate column Event mapped to old event. Intention is to help reader know which new symonfy event is mapped to the old event.
• Recheck if this table looks readable for an app developer.
• Recheck if the entries updated are correct.

Note: As of now I have used audit app as reference to update the table. Will cross check again.