PHP Flysystem 패키지를 V2 로 업그레이드하기

Flsystem 은 는 thephpleague.com 개발자 그룹에서 만든 파일 시스템 추상화(File system abstraction) 패키지입니다. 위치한 곳이 Local 디스크거나 AWS, FTP 인지 여부와 상관없이 동일한 Interface 로 파일과 디렉터리를 다룰 수 있습니다.

Flsystem 은 laravel 의 File Storage 로 채택되어서 라라벨 사용자에게는 이미 익숙한 패키지일 겁니다.

최근에 2.0 이 출시되고 1.0 과 아키텍처와 API 가 바뀌어서 기존 소스들은 수정이 필요합니다.

API 간소화

update, put 등 제거

기존에는 write 와 update 가 분리되어 있었지만 이번 버전에서는 하나로 합쳐지고 이에 따라 update, updateStream, put, updateStream 메서드는 삭제되었습니다.

V2부터는 파일을 쓰려면 기존 파일 존재 여부와 상관없이 무조건 write 나 writeStream 을 사용하면 됩니다.

try {
    $filesystem->write($path, $contents, $config);
} catch (FilesystemError | UnableToWriteFile $exception) {
    // handle the error
}

try {
    $filesystem->writeStream($path, $stream, $config);
} catch (FilesystemError | UnableToWriteFile $exception) {
    // handle the error
}

result 를 boolean 으로 return 하지 않음

예전에는 메서드 호출에 대한 결과 값을 boolean 으로 전달했으므로 이 값에 따라 분기해서 처리했습니다.

try {
    $success = $filesystem->write('path.txt', 'contents');

    if ($success) {
        // 성공시 처리
    } else {
        // 실패 처리
    }
} catch (Throwable $exception) {
    // 예외 처리
}

V2 에서는 result 하지 않고 실패시 Exception 을 Throw 하므로 return 값을 체크하지 않고 catch 구문에서 예외 처리를 해주면 됩니다.

try {
    $filesystem->write('path.txt', 'contents');
    // 성공 처리
} catch (FilesystemError $exception) {
    // 예외 처리
}

Error Handling with exceptions.

V2 에서는 에러 처리로 Exception 을 사용하므로 exception handling 이 필요합니다. 전체 예외 목록은 여기에서 확인할 수 있습니다.

더 나은 content listing 기능 제공

V2 부터는 개발자 경험 향상이 최우선 목표라 잘 알려진 문제들을 모두 해결했고 대표적인 예는 폴더내 목록을 가져오는 listContents 메서드입니다.

다양한 필터와 attribute 를 사용해서 컨텐츠를 필터링할 수 있으며 바뀐 사용법은 여기에서 확인할 수 있습니다.

Plugin 제거

V1 에서는 플러그인으로 기능을 확장할 수 있었지만 나쁜 디자인이나 안정성이 떨어지는 플러그인을 만드는 경우가 많아서 V2 에서는 삭제되었습니다.

대신 기능 확장이 필요하다면 Flysystem 밖에서 만들고 사용하면 됩니다.

그 외에 다른 변경 사항들은 아래 패키지 문서 링크를 보면 됩니다.

Ref

What is new in Flysystem V2 - Flysystem (thephpleague.com)

Laravel 과 PHP